diff --git a/.gitignore b/.gitignore
index b25c15b..56dd60b 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1 +1,4 @@
*~
+_site/
+review.txt*
+.#*
diff --git a/Gemfile.lock b/Gemfile.lock
index 6f5bef9..ff3b9c8 100644
--- a/Gemfile.lock
+++ b/Gemfile.lock
@@ -83,7 +83,7 @@ GEM
jekyll (>= 3.7, < 5.0)
jekyll-watch (2.2.1)
listen (~> 3.0)
- json (2.12.2)
+ json (2.16.0)
just-the-docs (0.10.1)
jekyll (>= 3.8.5)
jekyll-include-cache
diff --git a/REFACTOR.md b/REFACTOR.md
new file mode 100644
index 0000000..0c3883d
--- /dev/null
+++ b/REFACTOR.md
@@ -0,0 +1,636 @@
+
+# TrustGraph Documentation Refactoring Plan
+
+**Status**: In Progress - Phase 4 Complete
+**Started**: 2025-11-20
+**Target Completion**: TBD
+**Last Updated**: 2025-11-21
+
+## Overview
+
+This document outlines a comprehensive restructuring of the TrustGraph documentation to address structural issues, improve navigation, and enhance user experience.
+
+## Problems Identified
+
+### 1. Structure & Organization
+- **Getting Started vs Overview overlap**: `getting-started/concepts.md` duplicates overview content
+- **Installation embedded in index**: Quickstart guide is in `getting-started/index.md` instead of `installation.md`
+- **Maturity docs duplicated**: Real content in root `maturity.md`, empty placeholder in `overview/feature-maturity.md`
+- **Community section misnamed**: Contains project development/contributing info, not community interaction
+
+### 2. Navigation & Signposting
+- **Landing page lacks user journeys**: No personas, no clear paths for different users
+- **Section indexes too minimal**: All major sections lack proper signposting
+- **Deployment decisions unclear**: No guidance on local vs cloud, platform selection
+- **Examples vs Guides confusion**: Unclear distinction between tutorials, guides, and examples
+
+### 3. Content Gaps
+- **Missing RAG guides**: No how-to guides for DocumentRAG, GraphRAG, OntologyRAG
+- **Security documentation inadequate**: Only stubs, no real security guidance
+- **20+ placeholder pages**: Many sections are "Coming soon" with no content
+- **Guides index mismatch**: Lists 8 categories, only 4 exist
+
+### 4. Technical Issues
+- **GitHub edit links broken**: Points to wrong repository
+- **Build artifacts unignored**: `_site/` directory tracked in git
+- **Template leftovers**: Just-the-Docs template references still present
+- **Branch confusion**: Working on `master`, config specifies `main`
+
+---
+
+## Vision: What Good Looks Like
+
+When this refactoring is complete, the TrustGraph documentation will be:
+
+### User-Centric & Journey-Oriented
+
+**Landing Experience**:
+- A visitor arrives at docs.trustgraph.ai and immediately sees **their path** based on their role (developer, deployer, data scientist, contributor)
+- Within 30 seconds, they know exactly where to go for their immediate need
+- A clear "Get started in 5 minutes" path for the impatient
+- Value proposition is immediately clear: "TrustGraph helps you..."
+
+**Navigation Flow**:
+- Every section landing page answers: "What is this section for? Who should read it? Where should I start?"
+- No dead ends - every page links to logical next steps
+- Clear breadcrumbs showing "You are here, you came from there, you can go to..."
+- Consistent "See Also" sections connecting related content
+
+### Structurally Sound & Logically Organized
+
+**Information Architecture**:
+- **Getting Started**: Pure practical "how to run TrustGraph" - no theory
+- **Overview**: Pure conceptual "what is TrustGraph and why" - no installation steps
+- **Guides**: Task-oriented how-tos organized by workflow, not by component
+- **Reference**: Exhaustive technical details organized by API/CLI/config
+- **Examples**: Working code samples and datasets that demonstrate real use cases
+- **Contributing**: Everything needed to contribute to the project
+
+**Content Relationships**:
+- Zero duplication - each concept explained once, in the right place
+- Clear hierarchy: overview → guide → reference → example
+- Cross-references make connections explicit: "For the theory, see Overview/Architecture. For the implementation, see this guide."
+
+### Complete & Honest
+
+**Content Coverage**:
+- Core workflows documented: DocumentRAG, GraphRAG, OntologyRAG with complete examples
+- Security documented to production standards: authentication, encryption, access control, threat model
+- Deployment guidance includes decision frameworks, not just "here are options"
+- No "Coming soon" without context - every WIP page clearly states expected completion and why it matters
+
+**Quality Standards**:
+- Every guide is tested and works
+- Every example can be copy-pasted and run
+- Every API is documented with request/response examples
+- Every CLI command has a complete example with real output
+
+### Discoverable & Scannable
+
+**Finding Information**:
+- Search works excellently (already does)
+- Section indexes are comprehensive directories, not minimal lists
+- Comparison tables help choose between options (e.g., "When to use DocumentRAG vs GraphRAG")
+- Decision trees guide complex choices (e.g., "Which deployment option?")
+
+**Reading Experience**:
+- Clear headings allow skimming
+- Code examples are syntax-highlighted and commented
+- Callouts highlight warnings, tips, and important notes
+- Diagrams illustrate complex concepts
+
+### Production-Ready
+
+**Deployment Confidence**:
+- Clear path from "trying it locally" to "running in production"
+- Security considerations integrated into deployment guides, not separate
+- Performance guidance includes actual numbers and benchmarks
+- Troubleshooting sections answer real problems users face
+
+**Enterprise Readiness**:
+- Architecture diagrams show how components fit together at scale
+- High availability and disaster recovery documented
+- Monitoring and observability guidance
+- Cost optimization considerations
+
+### Maintainable & Sustainable
+
+**For Documentation Contributors**:
+- Clear guidelines on where new content goes
+- Templates for common page types (guide, API reference, tutorial)
+- Consistent terminology (documented glossary)
+- Automated link checking prevents broken references
+
+**For Product Development**:
+- Easy to keep docs in sync with code
+- Clear process for marking features as beta/stable/deprecated
+- Changelog integration shows what changed when
+
+---
+
+## Success Metrics
+
+When we've achieved this vision:
+
+1. **User can find their first-run guide in < 60 seconds** from landing page
+2. **Zero placeholder pages without WIP markers and expected dates**
+3. **Every major user journey documented end-to-end** (ingest data → query → get results)
+4. **Security reviewer can assess production-readiness** from documentation alone
+5. **New contributor can find "how to contribute" in < 30 seconds**
+6. **Zero broken internal links**
+7. **Search returns relevant results** for key terms like "authentication", "deploy", "query"
+8. **Each section index provides clear navigation guidance**, not just a list
+
+---
+
+## Refactoring Plan
+
+### Phase 1: Configuration & Cleanup ✅ COMPLETE
+
+**Goal**: Fix technical issues and prepare for restructuring
+
+1. **✅ Update `.gitignore`**
+ - ✅ Add `_site/` (Jekyll build output)
+ - ✅ Add `review.txt*` and temp files
+ - ✅ Add `.#*` (Emacs lock files)
+
+2. **✅ Fix `_config.yml`**
+ - ✅ Update `gh_edit_repository` to `https://github.com/trustgraph-ai/docs.trustgraph.ai`
+ - ✅ Remove template repository aux_link (line 10)
+ - ✅ Add WIP callout style for placeholder marking
+ - ✅ Verify `gh_edit_branch` matches actual workflow (confirmed: `main`)
+
+3. **✅ Add callout styles**
+ ```yaml
+ callouts:
+ warning:
+ title: Warning
+ color: red
+ wip:
+ title: Work in Progress
+ color: yellow
+ ```
+
+**Files affected**: `.gitignore`, `_config.yml`
+
+**Completed**: 2025-11-20
+
+---
+
+### Phase 2: Content Reorganization ✅ COMPLETE
+
+**Goal**: Move content to logical locations and eliminate duplication
+
+#### 2.1 ✅ Consolidate Maturity Documentation
+
+- ✅ **Move** `maturity.md` → `overview/maturity.md`
+- ✅ **Delete** `overview/feature-maturity.md` (empty placeholder)
+- ✅ **Update** navigation order in moved file (nav_order: 5, parent: Overview)
+- **Rationale**: Feature maturity is overview/meta information, belongs with architecture and features
+
+**Files affected**:
+- `maturity.md` → `overview/maturity.md` (moved)
+- `overview/feature-maturity.md` (deleted)
+
+#### 2.2 ✅ Restructure Getting Started
+
+- ✅ **Extract** quickstart from `getting-started/index.md` → `getting-started/quickstart.md`
+- ✅ **Simplify** `getting-started/index.md` to be a proper landing page with user journeys
+- ✅ **Move** conceptual content from `getting-started/concepts.md` → `overview/introduction.md`
+- ✅ **Rewrite** `getting-started/concepts.md` to focus on practical concepts needed for first steps
+- **Rationale**: Separate "learning about TrustGraph" from "getting TrustGraph running"
+
+**Files affected**:
+- `getting-started/index.md` (rewritten with user paths)
+- `getting-started/quickstart.md` (new, extracted 200-line quickstart)
+- `getting-started/concepts.md` (rewritten - practical focus)
+- `overview/introduction.md` (new, conceptual architecture content)
+
+#### 2.3 ✅ Rename Community Section
+
+- ✅ **Rename** `community/` → `contributing/` (directory and all references)
+- ✅ **Update** section title and description
+- ✅ **Reorganize** content:
+ - ✅ Keep: contributing.md, code-of-conduct.md, development-guide.md, developer.md
+ - ✅ Move: `roadmap.md` → `overview/roadmap.md`
+ - ✅ Move: `changelog/` → `reference/changelog/`
+ - ✅ Rename: `support.md` → `getting-help.md`
+- ✅ Update all parent references in child pages
+
+**Files affected**:
+- `community/` → `contributing/` (renamed)
+- `contributing/index.md` (rewritten)
+- `community/roadmap.md` → `overview/roadmap.md` (moved)
+- `community/changelog/` → `reference/changelog/` (moved)
+- `community/support.md` → `contributing/getting-help.md` (renamed)
+- All child pages updated with correct parent references
+
+#### 2.4 ✅ Clarify Examples vs Guides
+
+**Defined clear distinction**:
+- **Guides**: Task-oriented how-to instructions ("How do I...?")
+- **Examples**: Complete working code samples and datasets
+- **Tutorials**: Learning-oriented lessons (step-by-step learning paths)
+
+**Completed**:
+- ✅ Rewrite `examples/index.md` with clear scope and Examples vs Guides comparison table
+- ✅ Rewrite `guides/index.md` with clear scope, available guides listed, planned guides marked WIP
+- ✅ Add cross-references between sections
+- ✅ Document the distinction in both index pages
+
+**Files affected**:
+- `examples/index.md` (completely rewritten - clear scope, comparison table)
+- `guides/index.md` (completely rewritten - task finder table, WIP markers)
+
+**Completed**: 2025-11-20
+
+---
+
+### Phase 3: Navigation & Signposting ✅ COMPLETE
+
+**Goal**: Help users find what they need quickly
+
+#### 3.1 ✅ Rewrite Landing Page
+
+**File**: `index.md`
+
+**Completed**:
+- ✅ Added value proposition and tagline
+- ✅ Created 5 user journey paths:
+ - 👨💻 Developer (API integration, guides, examples)
+ - 🏗️ Deploying TrustGraph (deployment options, production)
+ - 📊 Data Scientist (GraphRAG, extraction, queries)
+ - 🏢 Evaluating TrustGraph (concepts, use cases, maturity)
+ - 🔧 Extending TrustGraph (contributing, custom development)
+- ✅ Added key features section with descriptions
+- ✅ Added documentation sections overview
+- ✅ Added "Quick Links by Task" table
+- ✅ Added getting help resources
+
+#### 3.2 ✅ Add Section Signposting
+
+**Completed for all major section indexes**:
+- ✅ Purpose statements ("This section is for...")
+- ✅ Audience identification
+- ✅ Navigation guides with "If you want X, see Y" patterns
+- ✅ Reading order recommendations
+- ✅ Prerequisites listed
+- ✅ Cross-references to other sections
+
+**Files updated**:
+- ✅ `overview/index.md` - 3 reading paths, quick answers, comparison tables
+- ✅ `deployment/index.md` - Decision tables, quick decision guide, production checklist, component architecture
+- ✅ `guides/index.md` - Already updated in Phase 2 with task finder table
+- ✅ `reference/index.md` - Quick find tables, API/CLI quick references, usage guidance
+- ✅ `examples/index.md` - Already updated in Phase 2 with Examples vs Guides comparison
+- ✅ `advanced/index.md` - Prerequisites, topic roadmap, decision table, contribution guide
+- ✅ `getting-started/index.md` - Already updated in Phase 2 with user paths
+
+#### 3.3 ✅ Create Deployment Decision Guide
+
+**File**: `deployment/choosing-deployment.md` (new)
+
+**Completed**:
+- ✅ Decision tree flowchart (text-based)
+- ✅ Comparison matrix by use case (6x5 table)
+- ✅ Comparison matrix by technical requirements (8x6 table)
+- ✅ Detailed profiles for all 8 deployment options:
+ - Docker Compose
+ - Minikube
+ - AWS EC2 Single Instance
+ - AWS RKE (Production)
+ - Azure AKS
+ - Google Cloud Platform
+ - Intel/Tiber Cloud
+ - Scaleway
+- ✅ Each profile includes: strengths, limitations, requirements, when to choose, cost estimates
+- ✅ Decision factors by scale, budget, and team expertise
+- ✅ Migration paths between deployment types
+- ✅ Next steps and links to specific guides
+
+**Also updated**: `deployment/index.md` features the choosing-deployment guide prominently with quick decision table
+
+**Completed**: 2025-11-20
+
+---
+
+### Phase 4: New Content Creation ✅ COMPLETE
+
+**Goal**: Fill critical content gaps
+
+#### 4.1 ✅ Create RAG Guides
+
+**Structure decision**: Created three separate RAG guides directly under `guides/` (not in a `guides/rag/` subdirectory)
+
+**Completed files**:
+
+1. **✅ `guides/graph-rag.md`** (nav_order: 10)
+ - Complete Graph RAG guide emphasizing relationship-aware retrieval
+ - What is GraphRAG and when to use it
+ - Knowledge graph structure and traversal
+ - Step-by-step implementation guide (load documents, extract entities, build graph, query)
+ - Common patterns: entity relationships, temporal queries, comparative analysis
+ - Advanced usage: controlling traversal depth, entity-focused queries
+ - Troubleshooting section (incomplete graphs, poor entity extraction, slow queries)
+ - Comparison with Document RAG and Ontology RAG
+
+2. **✅ `guides/ontology-rag.md`** (nav_order: 11)
+ - Complete Ontology/Structured RAG guide for schema-based extraction
+ - What is OntologyRAG and when to use it
+ - SDL (Schema Definition Language) examples and usage
+ - Step-by-step guide (define schema, load documents, extract data, query structured data)
+ - Natural language to GraphQL query conversion examples
+ - Common patterns: product catalogs, financial data, contacts, events
+ - Complex schemas with nested objects and arrays
+ - Validation and quality control
+ - Export to JSON/CSV
+
+3. **✅ `guides/document-rag.md`** (nav_order: 12)
+ - Complete Document RAG guide (mentions "basic RAG", "naive RAG", or just "RAG")
+ - What is DocumentRAG and when to use it
+ - Vector embeddings and semantic search explanation
+ - Step-by-step guide (prepare documents, configure chunking, load documents, process, query)
+ - Chunking configuration guidance (size, overlap)
+ - CLI, API, and Workbench query methods
+ - Understanding results: source attribution, confidence indicators
+ - Troubleshooting: poor retrieval, missing context, slow queries, empty results
+ - Advanced configuration: custom embedding models, retrieval tuning, collection management
+ - Comparison table with GraphRAG and OntologyRAG
+
+**Also updated**:
+- ✅ `guides/index.md` - Added comprehensive RAG workflow section with all three guides
+- ✅ Updated guides/index.md task finder table to include all three RAG types
+
+**Note**: User requested specific ordering: GraphRAG → Ontology RAG → Document RAG (achieved via nav_order values)
+
+#### 4.2 ✅ Create Security Documentation
+
+**New directory**: ✅ `guides/security/` created
+
+**Philosophy**: "Tell it like it is" - honest assessment of current features vs. enterprise roadmap, based on team's 20+ years cybersecurity experience
+
+**Completed files**:
+
+1. **✅ `guides/security/index.md`** (nav_order: 50)
+ - Security philosophy emphasizing honesty and real expertise
+ - Current status: strong foundations, enterprise features in development
+ - What exists today: Pulsar multi-tenant separation, optional service auth, infrastructure security
+ - Enterprise roadmap overview (MCP credentials, tamper-proof logging, enhanced multi-tenancy)
+ - Government AI security programme validation details
+ - Security recommendations by deployment type (Development, Kubernetes, Cloud)
+ - Production security checklist (network, auth, data protection, monitoring, infrastructure)
+ - What TrustGraph does differently: security-first architecture, real cybersec experience
+ - Reporting security issues and getting help
+
+2. **✅ `guides/security/current-features.md`** (nav_order: 1)
+ - Honest documentation of available security features today
+ - Multi-tenant data separation: Pulsar-based architecture, collection-based isolation
+ - Service authentication: optional inter-service auth, configuration examples, limitations
+ - Infrastructure security: Kubernetes deployment, Pulumi secret management, CI/CD security testing
+ - Network security: K8s network policies, TLS configuration
+ - Data security: encryption at rest (storage layer), encryption in transit (TLS)
+ - Access control: current state (application layer responsibility), recommendations
+ - Monitoring & audit: Grafana dashboards, Pulsar audit trail, gaps clearly stated
+ - Government security programme validation
+ - Security configuration examples (minimal/dev, basic/staging, enhanced/production)
+ - Clear about what's missing and what's the user's responsibility
+
+3. **✅ `guides/security/enterprise-roadmap.md`** (nav_order: 2)
+ - Comprehensive enterprise security roadmap with development status indicators
+ - Multi-layer MCP credential encryption (🔄 Active Development):
+ - Per-user credential management with vault isolation
+ - Multi-layer encryption (storage, transit, just-in-time decryption)
+ - Credential exposure minimization design
+ - Use cases: multi-tenant SaaS, enterprise, government/defense
+ - Timeline: Q1-Q3 2025
+ - Tamper-proof logging architecture (🔄 Active Development):
+ - Blockchain-inspired immutable log design
+ - Cryptographic verification and chain integrity
+ - Compliance support (SOC 2, GDPR, HIPAA, government standards)
+ - Timeline: Q2-Q4 2025
+ - Enhanced multi-tenant security (✅ Foundation complete, 🔄 Enhancements in development):
+ - Hard multi-tenancy guarantees with cryptographic isolation
+ - Injection attack protection (prompt injection, tool calling manipulation)
+ - Secure tool calling in agentic flows
+ - Universal service authentication (✅ Partial, 🔄 Being completed):
+ - Mandatory authentication for all services
+ - Automatic token rotation
+ - Zero-trust service mesh integration
+ - Additional roadmap: RBAC, DLP, security analytics, compliance certifications
+ - Enterprise security package tiers (Government/Defense, Enterprise SaaS, Enterprise On-Premise)
+ - Early access and influencing the roadmap
+ - Team experience and "why trust our roadmap" section
+
+**Also updated**:
+- ✅ `guides/index.md` - Added Security section with three guides listed
+
+**Key features of security docs**:
+- Honest about current state vs. planned features
+- Clear timeline estimates (not commitments)
+- Emphasizes team's real cybersecurity experience (Lyft, 20+ years)
+- Government AI security programme validation mentioned
+- MCP (Model Context Protocol) security focus for agentic systems
+- Pulsar-based multi-tenant architecture as foundation
+- "We don't oversell" philosophy throughout
+
+#### 4.3 Improve Deployment Guidance
+
+**Status**: 🎯 **Planned** (not yet started)
+
+**Planned enhancements**:
+
+1. **`deployment/production-considerations.md`**
+ - High availability setup
+ - Disaster recovery
+ - Monitoring and alerting
+ - Performance tuning
+ - Resource sizing
+ - Cost optimization
+
+2. **`deployment/minikube.md`**
+ - Add "When to use Minikube" section
+ - Add "Limitations" section
+ - Add "Moving to production" section
+
+3. **`deployment/docker-compose.md`**
+ - Add "When to use Docker Compose" section
+ - Add resource requirements
+ - Add scaling limitations
+
+**Note**: This sub-phase is optional/deferred pending review of Phase 4 RAG and security work.
+
+**Completed**: 2025-11-21
+
+---
+
+### Phase 5: Placeholder Management
+
+**Goal**: Mark all incomplete content clearly
+
+#### 5.1 Add WIP Callouts
+
+**For all placeholder pages, add at top**:
+```markdown
+{: .wip }
+> **Work in Progress**
+> This page is planned but not yet complete.
+> Expected completion: [DATE or "TBD"]
+> Track progress: [GitHub issue link if applicable]
+```
+
+**Files requiring WIP markers** (20+ files):
+- All files in `advanced/` (except index if rewritten)
+- `examples/tutorials/index.md`
+- `examples/integrations/index.md`
+- `reference/apis/api-document-load.md`
+- `guides/monitoring/index.md`
+- Any other identified stubs
+
+#### 5.2 Update Guides Index
+
+**File**: `guides/index.md`
+
+**Changes**:
+- Remove listed categories that don't exist (Data Integration, Querying, Visualization, Migration)
+- Add categories that DO exist (Agent Extraction, Object Extraction, Structured Processing)
+- Add new RAG section
+- Add new Security section
+- Mark WIP categories clearly
+- Organize logically
+
+---
+
+### Phase 6: Final Polish
+
+**Goal**: Ensure consistency and quality
+
+#### 6.1 Navigation Cleanup
+
+- Verify all `nav_order` values are logical
+- Ensure all `parent` relationships are correct
+- Remove orphaned pages
+- Fix duplicate nav_order conflicts
+
+#### 6.2 Cross-References
+
+- Add "See also" sections to related pages
+- Link between API docs and guides
+- Link between guides and CLI reference
+- Add breadcrumb hints where helpful
+
+#### 6.3 Link Validation
+
+- Test all internal links
+- Fix broken references
+- Verify "Edit on GitHub" links work
+- Check external links
+
+#### 6.4 Style Consistency
+
+- Consistent heading levels
+- Consistent code block formatting
+- Consistent callout usage
+- Consistent terminology
+
+---
+
+## Implementation Order
+
+### Iteration 1: Quick Wins (Day 1)
+- Phase 1: Configuration & Cleanup
+- Phase 5.1: Add WIP callouts to worst offenders
+- Fix landing page (Phase 3.1)
+
+### Iteration 2: Structural Fixes (Days 2-3)
+- Phase 2: Content Reorganization
+- Phase 5.2: Update guides index
+
+### Iteration 3: Navigation (Days 4-5)
+- Phase 3.2: Section signposting
+- Phase 3.3: Deployment decision guide
+- Phase 4.3: Deployment guidance improvements
+
+### Iteration 4: Content Creation (Days 6-10)
+- Phase 4.1: RAG guides (3 days)
+- Phase 4.2: Security documentation (2 days)
+
+### Iteration 5: Polish (Days 11-12)
+- Phase 6: Final polish
+- Review and testing
+
+---
+
+## Success Criteria
+
+- [ ] No placeholder content without WIP markers
+- [ ] All section indexes have clear signposting
+- [ ] Landing page provides clear user journeys
+- [ ] Getting Started and Overview have no overlap
+- [ ] RAG guides exist and are comprehensive
+- [ ] Security documentation adequate for production deployments
+- [ ] Deployment decision guidance clear and actionable
+- [ ] All navigation links work correctly
+- [ ] GitHub edit links functional
+- [ ] Clear distinction between Examples and Guides
+
+---
+
+## Files to Track
+
+### Moving
+- `maturity.md` → `overview/maturity.md`
+- `community/` → `contributing/`
+- `community/roadmap.md` → `overview/roadmap.md`
+- `community/changelog/` → `reference/changelog/`
+
+### Deleting
+- `overview/feature-maturity.md` (duplicate placeholder)
+- `deployment/security-considerations.md` (stub, replaced by guides/security/)
+- `review.txt` (temp file)
+
+### Creating (New Files)
+- ✅ `getting-started/quickstart.md`
+- ✅ `overview/introduction.md`
+- ✅ `deployment/choosing-deployment.md`
+- ✅ `guides/graph-rag.md` (changed: not in rag/ subdirectory)
+- ✅ `guides/ontology-rag.md` (changed: not in rag/ subdirectory)
+- ✅ `guides/document-rag.md` (changed: not in rag/ subdirectory)
+- ✅ `guides/security/index.md`
+- ✅ `guides/security/current-features.md` (changed from original plan)
+- ✅ `guides/security/enterprise-roadmap.md` (changed from original plan)
+- ❌ `guides/security/authentication.md` (not created - consolidated into current-features and enterprise-roadmap)
+- ❌ `guides/security/network-security.md` (not created - consolidated into current-features)
+- ❌ `guides/security/data-security.md` (not created - consolidated into current-features)
+- ❌ `guides/security/access-control.md` (not created - consolidated into current-features)
+
+### Rewriting (Major Changes)
+- `index.md` (landing page)
+- `getting-started/index.md`
+- `getting-started/concepts.md`
+- `overview/index.md`
+- `deployment/index.md`
+- `deployment/production-considerations.md`
+- `guides/index.md`
+- `examples/index.md`
+- All other section index files
+
+---
+
+## Notes
+
+- Keep git history intact - use `git mv` for moves
+- Create feature branches for each phase
+- Test Jekyll build after each major change
+- Get stakeholder review after Phase 3
+- Consider creating GitHub issues for each WIP page
+
+---
+
+## Questions to Resolve
+
+1. ~~Should we remove placeholders or mark them?~~ → Mark them clearly with WIP callouts
+2. ~~Create new content or just restructure?~~ → Create RAG guides, security docs, deployment guidance
+3. ~~Comprehensive or incremental?~~ → Comprehensive restructure
+4. What's the correct GitHub repository for edit links?
+5. Should Examples section be merged into Guides entirely?
+6. Timeline expectations for completion?
diff --git a/_config.yml b/_config.yml
index 98bbf4b..1036076 100644
--- a/_config.yml
+++ b/_config.yml
@@ -6,9 +6,6 @@ url: "https://docs.trustgraph.ai"
plugins:
- jekyll-sitemap
-aux_links:
- Template Repository: https://github.com/just-the-docs/just-the-docs-template
-
# logo: "/assets/images/just-the-docs.png"
# favicon_ico: "/assets/images/favicon.ico"
@@ -70,7 +67,7 @@ last_edit_time_format: "%b %e %Y at %I:%M %p" # uses ruby's time format: https:/
# Footer "Edit this page on GitHub" link text
gh_edit_link: true # show or hide edit this page link
gh_edit_link_text: "Edit this page on GitHub."
-gh_edit_repository: "https://github.com/trustgraph-ai/trustgraph-ai.github.io"
+gh_edit_repository: "https://github.com/trustgraph-ai/docs.trustgraph.ai"
gh_edit_branch: "main" # the branch that your docs is served from
# gh_edit_source: docs # the source that your files originate from
gh_edit_view_mode: "tree" # "tree" or "edit" if you want the user to jump into the editor immediately
@@ -82,6 +79,9 @@ callouts:
warning:
title: Warning
color: red
+ wip:
+ title: Work in Progress
+ color: yellow
# Exclude files and directories from Jekyll build
exclude:
@@ -91,3 +91,9 @@ exclude:
- .github/
- README.md
+defaults:
+ - scope:
+ path: ""
+ values:
+ layout: page
+
diff --git a/_includes/todo-banner.html b/_includes/todo-banner.html
new file mode 100644
index 0000000..b5a0c52
--- /dev/null
+++ b/_includes/todo-banner.html
@@ -0,0 +1,11 @@
+{% if page.todo %}
+
+ 🚧 This page needs work
+
+ {% if page.todo_notes %}
+ Note:
+ {{ page.todo_notes }}
+ {% endif %}
+
+
+{% endif %}
diff --git a/_layouts/page.html b/_layouts/page.html
new file mode 100644
index 0000000..ded7bf3
--- /dev/null
+++ b/_layouts/page.html
@@ -0,0 +1,7 @@
+---
+layout: default
+---
+
+{% include todo-banner.html %}
+
+{{ content }}
diff --git a/advanced/backup-restore.md b/advanced/backup-restore.md
index ed7fd2e..a9d6f2d 100644
--- a/advanced/backup-restore.md
+++ b/advanced/backup-restore.md
@@ -1,12 +1,14 @@
---
title: Backup & Restore
-layout: default
parent: Advanced Topics
grand_parent: TrustGraph Documentation
+todo: true
+todo_notes: This page is a placeholder and needs content to be added
+review_date: 2026-02-01
---
# Backup & Restore
FIXME: Coming soon
-This page will contain procedures for backing up and restoring TrustGraph data and configurations.
\ No newline at end of file
+This page will contain procedures for backing up and restoring TrustGraph data and configurations.
diff --git a/advanced/clustering.md b/advanced/clustering.md
index 2596ab4..e5b1036 100644
--- a/advanced/clustering.md
+++ b/advanced/clustering.md
@@ -1,12 +1,14 @@
---
title: Clustering
-layout: default
parent: Advanced Topics
grand_parent: TrustGraph Documentation
+todo: true
+todo_notes: This page is a placeholder and needs content to be added
+review_date: 2026-02-01
---
# Clustering
FIXME: Coming soon
-This page will contain guides for setting up multi-node clustering configurations in TrustGraph.
\ No newline at end of file
+This page will contain guides for setting up multi-node clustering configurations in TrustGraph.
diff --git a/advanced/custom-algorithms.md b/advanced/custom-algorithms.md
index 5755985..a344a75 100644
--- a/advanced/custom-algorithms.md
+++ b/advanced/custom-algorithms.md
@@ -1,12 +1,14 @@
---
title: Custom Algorithms
-layout: default
parent: Advanced Topics
grand_parent: TrustGraph Documentation
+todo: true
+todo_notes: This page is a placeholder and needs content to be added
+review_date: 2026-02-01
---
# Custom Algorithms
FIXME: Coming soon
-This page will contain guides for developing custom algorithms and extending TrustGraph's analytical capabilities.
\ No newline at end of file
+This page will contain guides for developing custom algorithms and extending TrustGraph's analytical capabilities.
diff --git a/advanced/disaster-recovery.md b/advanced/disaster-recovery.md
index dd7cbc2..8e4cf37 100644
--- a/advanced/disaster-recovery.md
+++ b/advanced/disaster-recovery.md
@@ -1,12 +1,14 @@
---
title: Disaster Recovery
-layout: default
parent: Advanced Topics
grand_parent: TrustGraph Documentation
+todo: true
+todo_notes: This page is a placeholder and needs content to be added
+review_date: 2026-02-01
---
# Disaster Recovery
FIXME: Coming soon
-This page will contain disaster recovery planning and procedures for TrustGraph systems.
\ No newline at end of file
+This page will contain disaster recovery planning and procedures for TrustGraph systems.
diff --git a/advanced/extending-trustgraph.md b/advanced/extending-trustgraph.md
index 2bd865b..494338d 100644
--- a/advanced/extending-trustgraph.md
+++ b/advanced/extending-trustgraph.md
@@ -1,12 +1,14 @@
---
title: Extending TrustGraph
-layout: default
parent: Advanced Topics
grand_parent: TrustGraph Documentation
+todo: true
+todo_notes: This page is a placeholder and needs content to be added
+review_date: 2026-02-01
---
# Extending TrustGraph
FIXME: Coming soon
-This page will contain guides for creating custom extensions and plugins for TrustGraph.
\ No newline at end of file
+This page will contain guides for creating custom extensions and plugins for TrustGraph.
diff --git a/advanced/index.md b/advanced/index.md
index 5807eef..74dedb1 100644
--- a/advanced/index.md
+++ b/advanced/index.md
@@ -1,26 +1,220 @@
---
title: Advanced Topics
-layout: default
nav_order: 11
has_children: true
parent: TrustGraph Documentation
+review_date: 2026-02-01
---
# Advanced Topics
-Advanced configuration, performance tuning, and extending TrustGraph.
+**Deep dives into performance, clustering, and customization**
-## Advanced Topics
+## What's in This Section?
+
+This section covers **advanced operational topics** for users who need to optimize performance, scale to multiple nodes, customize algorithms, or extend TrustGraph's functionality.
-- **[Custom Algorithms](custom-algorithms)** - Developing custom algorithms
-- **[Performance Tuning](performance-tuning)** - Optimization techniques
-- **[Clustering](clustering)** - Multi-node clustering setup
-- **[Backup & Restore](backup-restore)** - Data backup and recovery
-- **[Disaster Recovery](disaster-recovery)** - Disaster recovery planning
-- **[Extending TrustGraph](extending-trustgraph)** - Custom extensions and plugins
+### This Section is For:
+- **Performance engineers** optimizing TrustGraph deployments
+- **Platform architects** designing large-scale systems
+- **Advanced operators** managing complex deployments
+- **Developers** building custom extensions
+
+### Not What You Need?
+- **Just getting started?** → Begin with [Getting Started](../getting-started/)
+- **Deploying for first time?** → See [Deployment](../deployment/)
+- **Learning the basics?** → Read [Overview](../overview/)
## Prerequisites
-These topics assume familiarity with TrustGraph basics. Review [Getting Started](../getting-started/) first.
+Before diving into advanced topics:
+
+✅ **You should have**:
+- Successfully deployed TrustGraph (see [Getting Started](../getting-started/))
+- Basic understanding of TrustGraph architecture (see [Overview](../overview/))
+- Completed at least one workflow (see [How-to Guides](../guides/))
+
+⚠️ **These topics assume**:
+- Familiarity with distributed systems
+- Knowledge of Kubernetes (for clustering topics)
+- Understanding of performance profiling
+- Experience with system administration
+
+## Advanced Topics
+
+{: .wip }
+> **Work in Progress**
+> Most advanced topics are planned for future releases. Check back or contribute!
+
+### [Extending TrustGraph](extending-trustgraph)
+**Build custom functionality** - Develop custom processors, algorithms, and plugins.
+
+{: .wip }
+> Planned content includes:
+> - Custom processor development
+> - Plugin architecture
+> - Service extension patterns
+> - Integration hooks
+
+**When you need this**: Building custom extraction logic, integrating proprietary systems, or adding new capabilities.
+
+### [Performance Tuning](performance-tuning)
+**Optimize for speed and throughput** - Techniques for improving TrustGraph performance.
+
+{: .wip }
+> Planned content includes:
+> - Resource allocation tuning
+> - Query optimization
+> - Batch processing configuration
+> - Caching strategies
+> - Database tuning
+
+**When you need this**: Processing large document sets, handling high query volumes, or optimizing resource usage.
+
+### [Clustering](clustering)
+**Multi-node deployment** - Scale TrustGraph across multiple nodes for high availability and load distribution.
+
+{: .wip }
+> Planned content includes:
+> - Multi-node architecture
+> - Load balancing
+> - Service distribution
+> - State management
+> - Failover configuration
+
+**When you need this**: Scaling beyond single-node capacity, achieving high availability, or distributing workload.
+
+### [Backup & Restore](backup-restore)
+**Data protection** - Strategies for backing up and restoring TrustGraph data.
+
+{: .wip }
+> Planned content includes:
+> - Backup strategies
+> - Data export/import
+> - Point-in-time recovery
+> - Incremental backups
+> - Backup automation
+
+**When you need this**: Protecting production data, migrating between environments, or disaster recovery planning.
+
+### [Disaster Recovery](disaster-recovery)
+**Business continuity** - Planning and implementing disaster recovery for TrustGraph.
+
+{: .wip }
+> Planned content includes:
+> - DR strategy planning
+> - RTO/RPO considerations
+> - Failover procedures
+> - Recovery testing
+> - Geo-redundancy
+
+**When you need this**: Production deployments requiring business continuity guarantees.
+
+### [Custom Algorithms](custom-algorithms)
+**Algorithm development** - Implementing custom entity extraction and relationship discovery algorithms.
+
+{: .wip }
+> Planned content includes:
+> - Algorithm development framework
+> - Entity extraction customization
+> - Relationship discovery
+> - Custom ranking algorithms
+> - Integration with TrustGraph pipeline
+
+**When you need this**: Domain-specific extraction requirements or specialized knowledge graph construction.
+
+## Topic Roadmap
+
+### Available Now
+Currently, most advanced topics are in planning. The community welcomes contributions!
+
+### Coming Soon
+- **Performance Tuning** basics
+- **Extending TrustGraph** patterns
+- **Backup & Restore** procedures
+
+### Future Plans
+- Complete clustering guide
+- Disaster recovery playbooks
+- Custom algorithm development
+- Advanced monitoring
+- Multi-region deployment
+
+## When to Use Advanced Topics
+
+### Start Here If...
+
+| Your Situation | Relevant Topic |
+|----------------|----------------|
+| TrustGraph is too slow | [Performance Tuning](performance-tuning) |
+| Need high availability | [Clustering](clustering) |
+| Building custom features | [Extending TrustGraph](extending-trustgraph) |
+| Planning for failures | [Disaster Recovery](disaster-recovery) |
+| Need data backups | [Backup & Restore](backup-restore) |
+| Domain-specific extraction | [Custom Algorithms](custom-algorithms) |
+
+### Don't Start Here If...
+
+- ❌ You haven't deployed TrustGraph yet → [Getting Started](../getting-started/)
+- ❌ You don't understand basic concepts → [Overview](../overview/)
+- ❌ You're looking for common tasks → [How-to Guides](../guides/)
+- ❌ You need API documentation → [Reference](../reference/)
+
+## Contributing to Advanced Topics
+
+Many advanced topics are currently placeholders. We welcome contributions from the community!
+
+**How to contribute**:
+1. Review [Contributing Guidelines](../contributing/contributing)
+2. Check existing content and identify gaps
+3. Share your expertise with the community
+4. Submit pull requests with documentation
+
+**Especially valuable**:
+- Real-world performance tuning experiences
+- Clustering deployment lessons learned
+- Custom extension examples
+- Backup/restore procedures you've tested
+
+## Getting Help with Advanced Topics
+
+### Community Resources
+- **Discord** - Ask advanced questions in community channels
+- **GitHub Discussions** - Share your use cases and solutions
+- **GitHub Issues** - Report advanced configuration issues
+
+### Documentation
+- **[Troubleshooting](../deployment/troubleshooting)** - Operational issues
+- **[Reference](../reference/)** - Technical specifications
+- **[Examples](../examples/)** - Working code samples
+
+### Professional Support
+For enterprise deployments needing advanced configurations, consider:
+- Community consulting partnerships
+- Contributing your requirements to the roadmap
+- Participating in working groups
+
+## Next Steps
+
+### Not Finding What You Need?
+
+1. **Check if it's in another section**:
+ - [How-to Guides](../guides/) for task instructions
+ - [Reference](../reference/) for technical specs
+ - [Deployment](../deployment/) for setup guides
+
+2. **Search the documentation** (Ctrl+K)
+
+3. **Ask the community**:
+ - [Getting Help](../contributing/getting-help)
+ - Discord community
+ - GitHub Discussions
+
+4. **Contribute**:
+ - Share your advanced use cases
+ - Document your solutions
+ - Help build these guides
+
+---
-Coming soon - advanced configuration and extension guides!
+**Have advanced TrustGraph experience?** We'd love your contributions! See [Contributing](../contributing/) to get started.
diff --git a/advanced/performance-tuning.md b/advanced/performance-tuning.md
index 7ec5c7e..bada85f 100644
--- a/advanced/performance-tuning.md
+++ b/advanced/performance-tuning.md
@@ -1,12 +1,14 @@
---
title: Performance Tuning
-layout: default
parent: Advanced Topics
grand_parent: TrustGraph Documentation
+todo: true
+todo_notes: This page is a placeholder and needs content to be added
+review_date: 2026-02-01
---
# Performance Tuning
FIXME: Coming soon
-This page will contain optimization techniques and performance tuning strategies for TrustGraph deployments.
\ No newline at end of file
+This page will contain optimization techniques and performance tuning strategies for TrustGraph deployments.
diff --git a/benchmarks.md b/benchmarks.md
index fe411d8..5ba5059 100644
--- a/benchmarks.md
+++ b/benchmarks.md
@@ -1,8 +1,8 @@
---
-layout: default
title: Benchmarks
nav_order: 7
parent: TrustGraph Documentation
+review_date: 2026-02-01
---
# Benchmarks
diff --git a/community/index.md b/community/index.md
deleted file mode 100644
index 674d978..0000000
--- a/community/index.md
+++ /dev/null
@@ -1,26 +0,0 @@
----
-title: Community
-layout: default
-nav_order: 9
-has_children: true
-parent: TrustGraph Documentation
----
-
-# Community
-
-Join the TrustGraph community and contribute to the project.
-
-## Community Resources
-
-- **[Contributing](contributing)** - How to contribute to TrustGraph
-- **[Code of Conduct](code-of-conduct)** - Community guidelines
-- **[Support](support)** - Getting help and support
-- **[Roadmap](roadmap)** - Project roadmap and future plans
-- **[Changelog](changelog)** - Release notes and changes
-- **[Developer's Guide](developer)** - Information for developers and contributors
-
-## Getting Involved
-
-We welcome contributions! Start by reading our [Contributing Guidelines](contributing) and [Code of Conduct](code-of-conduct).
-
-Coming soon - community resources and contribution guides!
diff --git a/community/code-of-conduct.md b/contributing/code-of-conduct.md
similarity index 89%
rename from community/code-of-conduct.md
rename to contributing/code-of-conduct.md
index c4146cf..72e2ebb 100644
--- a/community/code-of-conduct.md
+++ b/contributing/code-of-conduct.md
@@ -1,8 +1,7 @@
---
title: Code of Conduct
-layout: default
nav_order: 6
-parent: Community
+parent: Contributing
---
# Code of Conduct
diff --git a/community/contributing.md b/contributing/contributing.md
similarity index 89%
rename from community/contributing.md
rename to contributing/contributing.md
index 7377980..872301a 100644
--- a/community/contributing.md
+++ b/contributing/contributing.md
@@ -1,12 +1,11 @@
---
-title: Contributing
-layout: default
-parent: Community
-nav_order: 3
+title: Contributing Guidelines
+parent: Contributing
+nav_order: 1
grand_parent: TrustGraph Documentation
---
-# Contributing
+# Contributing Guidelines
We welcome contributors to the TrustGraph Github project.
diff --git a/community/developer.md b/contributing/developer.md
similarity index 99%
rename from community/developer.md
rename to contributing/developer.md
index af50a98..6a56eea 100644
--- a/community/developer.md
+++ b/contributing/developer.md
@@ -1,8 +1,7 @@
---
title: Developer's Guide
-layout: default
nav_order: 4
-parent: Community
+parent: Contributing
---
# Developer Guide
diff --git a/community/development-guide.md b/contributing/development-guide.md
similarity index 99%
rename from community/development-guide.md
rename to contributing/development-guide.md
index 0958a77..a9a09aa 100644
--- a/community/development-guide.md
+++ b/contributing/development-guide.md
@@ -1,8 +1,7 @@
---
title: Running TrustGraph as a developer
-layout: default
nav_order: 5
-parent: Community
+parent: Contributing
---
This is a WORK IN PROGRESS!
diff --git a/community/support.md b/contributing/getting-help.md
similarity index 79%
rename from community/support.md
rename to contributing/getting-help.md
index 96d4727..151873f 100644
--- a/community/support.md
+++ b/contributing/getting-help.md
@@ -1,8 +1,7 @@
---
title: Support
-layout: default
nav_order: 9
-parent: Community
+parent: Contributing
---
# Support
diff --git a/contributing/index.md b/contributing/index.md
new file mode 100644
index 0000000..94cef89
--- /dev/null
+++ b/contributing/index.md
@@ -0,0 +1,69 @@
+---
+title: Contributing
+nav_order: 9
+has_children: true
+parent: TrustGraph Documentation
+---
+
+# Contributing to TrustGraph
+
+Welcome! We're glad you're interested in contributing to TrustGraph. This section contains everything you need to know about contributing to the project, whether you're fixing bugs, adding features, improving documentation, or helping with community support.
+
+## How to Contribute
+
+- **[Contributing Guidelines](contributing)** - How to contribute code, documentation, and more
+- **[Code of Conduct](code-of-conduct)** - Community standards and expectations
+- **[Developer's Guide](developer)** - Set up your development environment
+- **[Development Guide](development-guide)** - Development workflows and best practices
+- **[Getting Help](getting-help)** - Support resources for contributors
+
+## Project Resources
+
+- **[Roadmap](../overview/roadmap)** - Future plans and development priorities
+- **[Changelog](../reference/changelog/)** - Release notes and version history
+
+## Ways to Contribute
+
+###Code Contributions
+- Fix bugs and issues
+- Implement new features
+- Improve performance
+- Add tests
+
+### Documentation
+- Improve existing docs
+- Write guides and tutorials
+- Fix typos and errors
+- Add examples
+
+### Community Support
+- Answer questions on Discord
+- Help users troubleshoot issues
+- Share your use cases
+- Write blog posts
+
+### Testing & Feedback
+- Report bugs
+- Suggest features
+- Test new releases
+- Provide feedback
+
+## Getting Started
+
+1. **Read**: Start with our [Contributing Guidelines](contributing)
+2. **Set Up**: Follow the [Developer's Guide](developer) to set up your environment
+3. **Find Work**: Check open issues or propose new features
+4. **Code**: Make your changes following our development guide
+5. **Submit**: Create a pull request with your contribution
+
+## Community Guidelines
+
+We're committed to providing a welcoming and inclusive environment. Please read and follow our [Code of Conduct](code-of-conduct).
+
+## Questions?
+
+- Check [Getting Help](getting-help) for support resources
+- Join our Discord community
+- Open a discussion on GitHub
+
+Thank you for contributing to TrustGraph!
diff --git a/community/roadmap.png b/contributing/roadmap.png
similarity index 100%
rename from community/roadmap.png
rename to contributing/roadmap.png
diff --git a/deployment/aws-ec2.md b/deployment/aws-ec2.md
index 6b4dd62..56d0848 100644
--- a/deployment/aws-ec2.md
+++ b/deployment/aws-ec2.md
@@ -1,9 +1,9 @@
---
title: AWS EC2 Single Instance
-layout: default
nav_order: 7
parent: Deployment
grand_parent: TrustGraph Documentation
+review_date: 2025-11-21
---
# AWS EC2 Single Instance Deployment
diff --git a/deployment/aws-rke.md b/deployment/aws-rke.md
index 490e950..11fe7ca 100644
--- a/deployment/aws-rke.md
+++ b/deployment/aws-rke.md
@@ -1,9 +1,9 @@
---
title: Amazon Web Services (RKE)
-layout: default
nav_order: 9
parent: Deployment
grand_parent: TrustGraph Documentation
+review_date: 2025-11-21
---
# Amazon Web Services (RKE) Deployment
diff --git a/deployment/azure.md b/deployment/azure.md
index 527101d..4bcad1a 100644
--- a/deployment/azure.md
+++ b/deployment/azure.md
@@ -1,9 +1,9 @@
---
title: Azure AKS
-layout: default
nav_order: 5
parent: Deployment
grand_parent: TrustGraph Documentation
+review_date: 2025-11-21
---
# Microsoft Azure AKS Deployment
diff --git a/deployment/choosing-deployment.md b/deployment/choosing-deployment.md
new file mode 100644
index 0000000..c4350aa
--- /dev/null
+++ b/deployment/choosing-deployment.md
@@ -0,0 +1,437 @@
+---
+title: Choosing a Deployment
+nav_order: 1
+parent: Deployment
+grand_parent: TrustGraph Documentation
+review_date: 2025-11-21
+---
+
+# Choosing a Deployment Option
+
+**Decision guide to help you select the right deployment method for your needs**
+
+## Quick Decision Tree
+
+```
+Are you just trying TrustGraph for the first time?
+├─ YES → Docker Compose (15 minutes)
+└─ NO ↓
+
+Is this for production use?
+├─ NO (dev/test) ↓
+│ ├─ Need Kubernetes? → Minikube
+│ └─ Simple setup? → Docker Compose
+└─ YES (production) ↓
+
+ Do you need high availability and scaling?
+ ├─ NO (small scale) ↓
+ │ ├─ On AWS? → AWS EC2 Single Instance
+ │ └─ Elsewhere? → Docker Compose
+ └─ YES (enterprise scale) ↓
+
+ Which cloud are you using?
+ ├─ AWS → AWS RKE
+ ├─ Azure → Azure AKS
+ ├─ GCP → Google Cloud Platform
+ ├─ Need GPU acceleration? → Intel/Tiber Cloud
+ └─ Budget-conscious? → Scaleway
+```
+
+## Comparison Matrix
+
+### By Use Case
+
+| Deployment | First Try | Dev/Test | Small Prod | Enterprise | GPU Workloads |
+|------------|-----------|----------|------------|------------|---------------|
+| **Docker Compose** | ✅ Best | ✅ Great | ⚠️ Limited | ❌ No | ❌ No |
+| **Minikube** | ⚠️ Complex | ✅ Great | ❌ No | ❌ No | ❌ No |
+| **AWS EC2** | ❌ Slow | ✅ Good | ✅ Good | ⚠️ Limited | ❌ No |
+| **AWS RKE** | ❌ Complex | ⚠️ Costly | ✅ Good | ✅ Best | ⚠️ Possible |
+| **Azure AKS** | ❌ Complex | ⚠️ Costly | ✅ Good | ✅ Best | ⚠️ Possible |
+| **GCP** | ❌ Complex | ✅ Good | ✅ Good | ✅ Best | ✅ Great |
+| **Intel/Tiber** | ❌ Complex | ⚠️ Specialty | ✅ Good | ✅ Good | ✅ Best |
+| **Scaleway** | ❌ Complex | ✅ Good | ✅ Good | ⚠️ Limited | ❌ No |
+
+### By Technical Requirements
+
+| Deployment | Setup Time | Complexity | HA Support | Auto-Scale | Cost |
+|------------|------------|------------|------------|------------|------|
+| **Docker Compose** | 15 min | Low | ❌ | ❌ | Free |
+| **Minikube** | 30 min | Medium | ❌ | ❌ | Free |
+| **AWS EC2** | 1 hour | Low | ❌ | ❌ | $ |
+| **AWS RKE** | 2-3 hours | High | ✅ | ✅ | $$$ |
+| **Azure AKS** | 2-3 hours | High | ✅ | ✅ | $$$ |
+| **GCP** | 2-3 hours | High | ✅ | ✅ | $$ |
+| **Intel/Tiber** | 2-4 hours | High | ✅ | ✅ | $$-$$$ |
+| **Scaleway** | 2-3 hours | Medium | ✅ | ✅ | $ |
+
+**Legend**:
+- ✅ = Excellent support
+- ⚠️ = Limited or conditional
+- ❌ = Not supported
+- $ = Low cost, $$ = Medium, $$$ = High
+
+## Detailed Deployment Profiles
+
+### Docker Compose
+
+**Best for**: First-time users, POCs, local development, small teams
+
+**Strengths**:
+- ✅ Fastest setup (15 minutes)
+- ✅ Simplest architecture
+- ✅ Easy to tear down and restart
+- ✅ No cloud costs
+- ✅ Complete control
+
+**Limitations**:
+- ❌ Single machine only
+- ❌ No automatic scaling
+- ❌ No built-in HA
+- ❌ Manual backup/restore
+
+**Resource Requirements**:
+- 8GB RAM minimum
+- 4 CPU cores minimum
+- 20GB disk space
+- Docker or Podman
+
+**When to choose**:
+- First time trying TrustGraph
+- Local development
+- Small document sets (<10k documents)
+- Budget constraints
+- Learning and experimentation
+
+**Migration path**: Can export data and migrate to cloud deployments later.
+
+---
+
+### Minikube
+
+**Best for**: Kubernetes learning, K8s deployment testing
+
+**Strengths**:
+- ✅ Real Kubernetes environment
+- ✅ Test K8s manifests locally
+- ✅ Good for learning
+- ✅ No cloud costs
+
+**Limitations**:
+- ❌ Single node
+- ❌ Resource intensive
+- ❌ Not for production
+- ❌ Complex setup
+
+**Resource Requirements**:
+- 16GB RAM recommended
+- 8 CPU cores recommended
+- 50GB disk space
+- Minikube, kubectl
+
+**When to choose**:
+- Learning Kubernetes
+- Testing K8s deployments before cloud
+- Validating manifests
+- K8s-based development workflow
+
+---
+
+### AWS EC2 Single Instance
+
+**Best for**: Simple AWS deployments, small production workloads
+
+**Strengths**:
+- ✅ Simple AWS deployment
+- ✅ Cost-effective for small scale
+- ✅ Easy to manage
+- ✅ AWS integration
+
+**Limitations**:
+- ❌ No automatic scaling
+- ❌ Single point of failure
+- ❌ Limited to instance size
+- ⚠️ Manual backup required
+
+**Resource Requirements**:
+- t3.xlarge or larger
+- 50GB+ EBS volume
+- Security groups configured
+- AWS account
+
+**When to choose**:
+- Small AWS deployments
+- <100 concurrent users
+- Development/staging on AWS
+- Simple operational model
+- Cost-conscious production
+
+**Cost estimate**: $100-200/month for t3.xlarge
+
+---
+
+### AWS RKE (Production Kubernetes)
+
+**Best for**: Enterprise AWS deployments, high availability
+
+**Strengths**:
+- ✅ Full HA support
+- ✅ Auto-scaling
+- ✅ Production-grade
+- ✅ AWS managed services integration
+- ✅ RKE2 security hardening
+
+**Limitations**:
+- ⚠️ Complex setup
+- ⚠️ Higher cost
+- ⚠️ Requires K8s expertise
+- ⚠️ Operational overhead
+
+**Resource Requirements**:
+- Multiple EC2 instances
+- RDS, EBS, ELB
+- VPC configuration
+- Terraform knowledge helpful
+
+**When to choose**:
+- Production deployments on AWS
+- Need high availability
+- Scaling requirements
+- Compliance requirements
+- Enterprise features needed
+
+**Cost estimate**: $500-2000+/month depending on scale
+
+---
+
+### Azure AKS
+
+**Best for**: Azure-committed organizations, enterprise deployments
+
+**Strengths**:
+- ✅ Managed Kubernetes
+- ✅ Azure integration
+- ✅ Enterprise support
+- ✅ HA and scaling
+- ✅ Azure Active Directory integration
+
+**Limitations**:
+- ⚠️ Complex setup
+- ⚠️ Higher cost
+- ⚠️ Azure vendor lock-in
+- ⚠️ Requires K8s expertise
+
+**Resource Requirements**:
+- AKS cluster
+- Azure Storage
+- Load balancers
+- Azure account
+
+**When to choose**:
+- Already on Azure
+- Enterprise Azure commitment
+- Need Microsoft support
+- Azure service integration
+
+**Cost estimate**: $500-2000+/month
+
+---
+
+### Google Cloud Platform
+
+**Best for**: GCP users, ML/AI workloads, VertexAI integration
+
+**Strengths**:
+- ✅ GKE managed Kubernetes
+- ✅ VertexAI integration
+- ✅ ML/AI optimized
+- ✅ Free credits available
+- ✅ Good for AI projects
+
+**Limitations**:
+- ⚠️ Complex setup
+- ⚠️ GCP vendor lock-in
+- ⚠️ Requires K8s expertise
+
+**Resource Requirements**:
+- GKE cluster
+- Cloud Storage
+- Load balancers
+- GCP account
+
+**When to choose**:
+- Already on GCP
+- Using VertexAI for LLMs
+- ML/AI focused projects
+- Google technology stack
+
+**Cost estimate**: $400-1800+/month (free credits help)
+
+---
+
+### Intel / Tiber Cloud
+
+**Best for**: GPU-accelerated workloads, high-performance computing
+
+**Strengths**:
+- ✅ GPU acceleration
+- ✅ Intel optimizations
+- ✅ High performance
+- ✅ Specialized hardware
+
+**Limitations**:
+- ⚠️ Complex setup
+- ⚠️ Specialized platform
+- ⚠️ Variable pricing
+
+**Resource Requirements**:
+- Intel GPU instances
+- Specialized configuration
+- Intel platform familiarity
+
+**When to choose**:
+- Need GPU acceleration
+- High-performance requirements
+- Large-scale processing
+- Intel hardware preference
+
+**Cost estimate**: Variable, contact for pricing
+
+---
+
+### Scaleway
+
+**Best for**: Budget-conscious deployments, EU data residency
+
+**Strengths**:
+- ✅ Lower cost than major clouds
+- ✅ European data centers
+- ✅ GDPR compliance
+- ✅ Kubernetes support
+
+**Limitations**:
+- ⚠️ Smaller ecosystem
+- ⚠️ Less mature than major clouds
+- ⚠️ Limited regions
+
+**Resource Requirements**:
+- Scaleway Kubernetes
+- Object storage
+- Load balancers
+- Scaleway account
+
+**When to choose**:
+- Budget constraints
+- EU data residency required
+- European operations
+- Cost-effective scaling
+
+**Cost estimate**: $200-1000+/month
+
+---
+
+## Decision Factors
+
+### By Scale
+
+**<1,000 documents**:
+- Docker Compose (local)
+- AWS EC2 Single (cloud)
+
+**1,000 - 50,000 documents**:
+- Docker Compose (powerful machine)
+- AWS EC2 Single Instance
+- Scaleway
+
+**50,000 - 500,000 documents**:
+- AWS RKE
+- Azure AKS
+- GCP
+- Scaleway
+
+**500,000+ documents**:
+- AWS RKE (with scaling)
+- Azure AKS (with scaling)
+- GCP (with scaling)
+- Intel/Tiber (with GPU)
+
+### By Budget
+
+**$0 (free)**:
+- Docker Compose
+- Minikube
+
+**<$200/month**:
+- AWS EC2 Single Instance
+- Scaleway (small)
+
+**$200-1000/month**:
+- Scaleway (medium)
+- GCP (with free credits)
+- AWS RKE (minimal)
+
+**$1000+/month**:
+- AWS RKE (production)
+- Azure AKS (production)
+- GCP (production)
+- Intel/Tiber
+
+### By Team Expertise
+
+**Beginner**:
+- Docker Compose
+
+**Intermediate**:
+- AWS EC2 Single Instance
+- Minikube
+- Scaleway
+
+**Advanced**:
+- AWS RKE
+- Azure AKS
+- GCP
+- Intel/Tiber
+
+## Migration Paths
+
+### From Docker Compose to Cloud
+
+1. Export your data using backup tools
+2. Set up cloud deployment
+3. Import data to cloud instance
+4. Validate and cutover
+
+### From Single Instance to Kubernetes
+
+1. Move to managed K8s (AKS, GKE, or RKE)
+2. Use Kubernetes manifests
+3. Implement HA and scaling
+4. Migrate data
+
+### Between Cloud Providers
+
+1. Export knowledge graphs and configurations
+2. Deploy to new cloud
+3. Import data
+4. Reconfigure integrations
+
+## Next Steps
+
+### Ready to Deploy?
+
+1. **Selected your option?** → Go to the specific deployment guide
+2. **Still unsure?** → Start with [Docker Compose](docker-compose) to try it out
+3. **Need help deciding?** → Ask in [community support](../contributing/getting-help)
+
+### Before Production
+
+Review these critical guides:
+- [Production Considerations](production-considerations) - HA, monitoring, backups
+- [Security Guide](../guides/security/) - Authentication and encryption (Phase 4)
+- [Troubleshooting](troubleshooting) - Common issues
+
+### Get Started
+
+- **[Docker Compose](docker-compose)** - Quickest way to start
+- **[Deployment Index](index)** - All deployment options
+- **[Getting Started](../getting-started/)** - Complete beginner guide
diff --git a/deployment/docker-compose.md b/deployment/docker-compose.md
index e6b2407..7457063 100644
--- a/deployment/docker-compose.md
+++ b/deployment/docker-compose.md
@@ -1,9 +1,9 @@
---
title: Docker Compose / Podman Compose
-layout: default
nav_order: 1
parent: Deployment
grand_parent: TrustGraph Documentation
+review_date: 2025-11-21
---
# Docker/Podman Compose Deployment
diff --git a/deployment/gcp.md b/deployment/gcp.md
index 3f2a50e..c9f0c95 100644
--- a/deployment/gcp.md
+++ b/deployment/gcp.md
@@ -1,9 +1,9 @@
---
title: Google Cloud Platform
-layout: default
nav_order: 6
parent: Deployment
grand_parent: TrustGraph Documentation
+review_date: 2025-11-21
---
# Google Cloud Platform Deployment
diff --git a/deployment/index.md b/deployment/index.md
index a2855f7..5d74a86 100644
--- a/deployment/index.md
+++ b/deployment/index.md
@@ -1,36 +1,195 @@
---
title: Deployment
-layout: default
nav_order: 4
has_children: true
parent: TrustGraph Documentation
+review_date: 2025-11-21
---
# Deployment Guide
-Deploy TrustGraph on various platforms and environments with these comprehensive guides.
+**Deploy and operate TrustGraph across different environments**
+
+## What's in This Section?
+
+This section provides **platform-specific deployment instructions** for running TrustGraph in various environments, from local development to production cloud deployments.
+
+### This Section is For:
+- **DevOps engineers** deploying TrustGraph infrastructure
+- **System administrators** managing TrustGraph instances
+- **Developers** setting up local development environments
+- **Architects** planning production deployments
+
+### Not What You Need?
+- **First time user?** → Start with [Quick Start](../getting-started/quickstart)
+- **Understanding concepts?** → See [Overview](../overview/)
+- **Looking for how-tos?** → Check [Guides](../guides/)
+
+## Choosing Your Deployment
+
+Not sure which deployment option fits your needs? See **[Choosing a Deployment](choosing-deployment)** for a decision guide with comparison tables and recommendations.
+
+### Quick Decision Guide
+
+| Your Situation | Recommended Option |
+|----------------|-------------------|
+| First time trying TrustGraph | [Docker Compose](docker-compose) |
+| Local development & testing | [Docker Compose](docker-compose) or [Minikube](minikube) |
+| Learning Kubernetes | [Minikube](minikube) |
+| Small production (<100 users) | [AWS EC2 Single Instance](aws-ec2) or [Docker Compose](docker-compose) |
+| Production with scaling needs | [AWS RKE](aws-rke), [Azure AKS](azure), or [GCP](gcp) |
+| GPU acceleration required | [Intel/Tiber Cloud](intel) |
+| Budget-conscious cloud | [Scaleway](scaleway) |
## Deployment Options
### Local Development
-- **[Docker Compose](docker-compose)** - Quick local deployment
-- **[Minikube](minikube)** - Local Kubernetes deployment
+
+Perfect for testing, development, and evaluation.
+
+#### [Docker Compose](docker-compose)
+**Easiest way to get started** - Deploy TrustGraph locally with all services orchestrated.
+
+- ✅ **Best for**: First-time users, POCs, local development
+- ✅ **Pros**: Simple setup, all-in-one, easy to tear down
+- ⚠️ **Limits**: Single machine, not for production scale
+- **Time to deploy**: 15 minutes
+- **Prerequisites**: Docker/Podman, 8GB RAM, 4 CPU cores
+
+#### [Minikube](minikube)
+**Local Kubernetes** - Run TrustGraph on Kubernetes locally.
+
+- ✅ **Best for**: Learning K8s, testing K8s deployments
+- ✅ **Pros**: Real Kubernetes environment, good for learning
+- ⚠️ **Limits**: Single node, resource intensive
+- **Time to deploy**: 30 minutes
+- **Prerequisites**: Minikube, kubectl, 16GB RAM recommended
### Cloud Platforms
-- **[Intel GPU / Tiber Cloud](intel)** - Intel accelerated high-performance deployment
-- **[Azure AKS](azure)** - Microsoft Azure deployment with AKS
-- **[Google Cloud Platform](gcp)** - GCP deployment guide
-- **[AWS EC2 Single Instance](aws-ec2)** - Simple AWS EC2 deployment for development
-- **[Amazon Web Services (RKE)](aws-rke)** - Production-ready AWS deployment with RKE2
-- **[Scaleway](scaleway)** - Scaleway deployment guide
-## Best Practices
+Production-ready deployments with scalability.
+
+#### [AWS (Amazon Web Services)](aws-rke)
+**Production AWS with RKE2** - Enterprise-ready deployment on AWS.
+
+- ✅ **Best for**: Production deployments, enterprise scale
+- ✅ **Pros**: High availability, auto-scaling, managed services
+- 💰 **Cost**: Medium to high (depends on resources)
+- **Time to deploy**: 2-3 hours
+- **Also see**: [AWS EC2 Single Instance](aws-ec2) for simpler development setup
+
+#### [Azure AKS](azure)
+**Microsoft Azure Kubernetes** - Deploy on Azure with AKS.
+
+- ✅ **Best for**: Azure-committed organizations
+- ✅ **Pros**: Azure integration, managed K8s, enterprise support
+- 💰 **Cost**: Medium to high
+- **Time to deploy**: 2-3 hours
+
+#### [Google Cloud Platform](gcp)
+**GCP deployment** - Run TrustGraph on Google Cloud.
+
+- ✅ **Best for**: GCP users, ML/AI workloads
+- ✅ **Pros**: VertexAI integration, GKE, good for AI projects
+- 💰 **Cost**: Medium (free credits available)
+- **Time to deploy**: 2-3 hours
+
+#### [Intel / Tiber Cloud](intel)
+**GPU-accelerated** - High-performance with Intel GPU acceleration.
+
+- ✅ **Best for**: GPU workloads, high-performance needs
+- ✅ **Pros**: Hardware acceleration, optimized for Intel
+- 💰 **Cost**: Variable
+- **Time to deploy**: 2-4 hours
+
+#### [Scaleway](scaleway)
+**Budget-friendly European cloud** - Cost-effective cloud deployment.
+
+- ✅ **Best for**: Budget-conscious deployments, EU data residency
+- ✅ **Pros**: Lower cost, European data centers
+- 💰 **Cost**: Lower than major clouds
+- **Time to deploy**: 2-3 hours
+
+#### [AWS EC2 Single Instance](aws-ec2)
+**Simple AWS setup** - Single EC2 instance for development/testing.
+
+- ✅ **Best for**: Development, small-scale testing on AWS
+- ✅ **Pros**: Simple, cost-effective for development
+- ⚠️ **Limits**: Not for production scale
+- 💰 **Cost**: Low
+- **Time to deploy**: 1 hour
+
+## Production Considerations
+
+### Before Going to Production
+
+Review these critical resources:
+
+1. **[Production Considerations](production-considerations)** - HA, monitoring, backups, disaster recovery
+2. **[Security Guide](../guides/security/)** - Authentication, encryption, access control (Phase 4)
+3. **[Choosing a Deployment](choosing-deployment)** - Detailed comparison and requirements
+
+### Production Checklist
+
+- [ ] High availability configured
+- [ ] Monitoring and alerting set up
+- [ ] Backup strategy implemented
+- [ ] Security hardening completed
+- [ ] Resource sizing validated
+- [ ] Disaster recovery plan tested
+- [ ] Performance benchmarks established
+- [ ] Documentation for operations team
+
+## Troubleshooting
+
+### Common Issues
+
+See **[Troubleshooting Guide](troubleshooting)** for solutions to common deployment problems:
+- Container startup failures
+- Network connectivity issues
+- Resource constraints
+- Configuration errors
+- Service dependencies
+
+### Getting Help
+
+- **[Troubleshooting Guide](troubleshooting)** - Detailed problem-solving
+- **[Getting Help](../contributing/getting-help)** - Community support
+- **[GitHub Issues](https://github.com/trustgraph-ai/trustgraph/issues)** - Report bugs
+
+## Deployment Architecture
+
+### Components
+
+TrustGraph deployments typically include:
+
+- **Processing Services**: Document processing, entity extraction, GraphRAG
+- **Storage Layer**: Graph database (Cassandra), vector store (Qdrant)
+- **Message Queue**: Apache Pulsar for service communication
+- **LLM Integration**: Connection to local or cloud LLMs
+- **Web Interface**: TrustGraph Workbench
+- **Monitoring**: Grafana dashboards (optional but recommended)
+
+### Network Requirements
+
+- **Internal**: Service-to-service communication
+- **External**: API access, web interface
+- **LLM Access**: Outbound to cloud LLMs or local model access
+- **Storage**: Persistent volumes for databases
-- **[Production Considerations](production-considerations)** - Production best practices
-- **[Security Considerations](security-considerations)** - Security best practices
-- **[Troubleshooting](troubleshooting)** - Common deployment issues
+## Next Steps
-## Getting Started
+### Just Starting?
+1. Try [Docker Compose](docker-compose) locally
+2. Load sample data: [Getting Started](../getting-started/quickstart)
+3. Explore features: [How-to Guides](../guides/)
-For quick local testing, start with [Docker Compose](docker-compose). For production deployments, review [Production Considerations](production-considerations) first.
+### Planning Production?
+1. Read [Choosing a Deployment](choosing-deployment)
+2. Review [Production Considerations](production-considerations)
+3. Set up monitoring and security
+4. Select your cloud platform guide above
+### Need Help?
+- Check [Troubleshooting](troubleshooting) for common issues
+- Visit [Getting Help](../contributing/getting-help) for support options
diff --git a/deployment/intel.md b/deployment/intel.md
index ccfb51a..0a4d638 100644
--- a/deployment/intel.md
+++ b/deployment/intel.md
@@ -1,9 +1,9 @@
---
title: Intel GPU / Tiber Cloud
-layout: default
nav_order: 3
parent: Deployment
grand_parent: TrustGraph Documentation
+review_date: 2025-11-21
---
# Intel Tiber Cloud Deployment
diff --git a/deployment/minikube.md b/deployment/minikube.md
index cc34924..47f914a 100644
--- a/deployment/minikube.md
+++ b/deployment/minikube.md
@@ -1,9 +1,9 @@
---
title: Minikube
-layout: default
nav_order: 2
parent: Deployment
grand_parent: TrustGraph Documentation
+review_date: 2025-11-21
---
# Minikube Deployment
diff --git a/deployment/ovhcloud.md b/deployment/ovhcloud.md
index bf9d9e3..9b3c613 100644
--- a/deployment/ovhcloud.md
+++ b/deployment/ovhcloud.md
@@ -1,9 +1,9 @@
---
title: OVHcloud
-layout: default
nav_order: 4.5
parent: Deployment
grand_parent: TrustGraph Documentation
+review_date: 2025-11-21
---
# OVHcloud Deployment
diff --git a/deployment/production-considerations.md b/deployment/production-considerations.md
index c8b9d2a..0ede2cd 100644
--- a/deployment/production-considerations.md
+++ b/deployment/production-considerations.md
@@ -1,9 +1,9 @@
---
title: Production Considerations
-layout: default
nav_order: 11
parent: Deployment
grand_parent: TrustGraph Documentation
+review_date: 2025-11-21
---
# Production Considerations
diff --git a/deployment/scaleway.md b/deployment/scaleway.md
index ac1033c..bb330ce 100644
--- a/deployment/scaleway.md
+++ b/deployment/scaleway.md
@@ -1,9 +1,9 @@
---
title: Scaleway
-layout: default
nav_order: 4
parent: Deployment
grand_parent: TrustGraph Documentation
+review_date: 2025-11-21
---
# Scaleway Deployment
diff --git a/deployment/security-considerations.md b/deployment/security-considerations.md
index 9437275..83e69af 100644
--- a/deployment/security-considerations.md
+++ b/deployment/security-considerations.md
@@ -1,9 +1,9 @@
---
title: Security Considerations
-layout: default
nav_order: 10
parent: Deployment
grand_parent: TrustGraph Documentation
+review_date: 2025-11-21
---
# Security Considerations
diff --git a/deployment/troubleshooting.md b/deployment/troubleshooting.md
index f876b30..cee20ac 100644
--- a/deployment/troubleshooting.md
+++ b/deployment/troubleshooting.md
@@ -1,9 +1,11 @@
---
title: Troubleshooting
-layout: default
nav_order: 12
parent: Deployment
grand_parent: TrustGraph Documentation
+review_date: 2026-02-01
+todo: true
+todo_notes: This is all placeholder text and needs content to be added.
---
# Deployment Troubleshooting
diff --git a/examples/index.md b/examples/index.md
index fc7cf5a..1428504 100644
--- a/examples/index.md
+++ b/examples/index.md
@@ -1,6 +1,5 @@
---
title: Examples
-layout: default
nav_order: 10
has_children: true
parent: TrustGraph Documentation
@@ -8,19 +7,111 @@ parent: TrustGraph Documentation
# Examples
-Real-world examples and sample implementations using TrustGraph.
+**Working code samples, datasets, and complete implementations you can copy and use.**
+
+Examples provide **ready-to-use code and data** that demonstrate TrustGraph features in action. Unlike guides that teach you *how* to do something, examples show you *what* working implementations look like.
+
+## What's in This Section?
+
+**Examples** include:
+- Complete working code samples
+- Sample datasets and data generators
+- Integration examples with real systems
+- Reference implementations
+
+**Not sure if you're in the right place?**
+- Want step-by-step instructions? See [How-to Guides](../guides/)
+- Want to understand concepts? See [Overview](../overview/)
+- Want API documentation? See [Reference](../reference/)
+
+## Available Examples
+
+### Sample Data
+- **[Sample Data](sample-data/)** - Example datasets for testing and development
+ - Pre-built knowledge graphs
+ - Sample documents (PDFs, text files)
+ - Test data generators
+
+### Working Code
+- **[NLP to Structured Queries](nlp-structured-queries)** - Convert natural language to GraphQL queries
+
+## Planned Examples
+
+{: .wip }
+> **Work in Progress**
+> The following examples are planned for future releases:
+
+- **[Tutorials](tutorials/)** - Complete end-to-end learning paths
+- **[Integrations](integrations/)** - Real-world system integration examples
+ - LangChain integration
+ - LlamaIndex integration
+ - Custom API integration
+ - Database connectors
+
+## How to Use Examples
+
+### 1. Browse Examples
+Find an example that matches your use case
+
+### 2. Copy the Code
+Examples are designed to be copied and adapted
+
+### 3. Run & Modify
+Test the example, then customize for your needs
+
+### 4. Refer to Guides
+For deeper understanding, see related [How-to Guides](../guides/)
## Example Categories
-### Tutorials
-- **[Tutorials](tutorials/)** - Step-by-step tutorials
-- **[Sample Data](sample-data/)** - Sample datasets and generators
-- **[Integrations](integrations/)** - Integration examples
+### By Use Case
+
+| Use Case | Example |
+|----------|---------|
+| Testing TrustGraph | [Sample Data](sample-data/) |
+| Natural language queries | [NLP to Structured Queries](nlp-structured-queries) |
+
+## Examples vs. Guides: What's the Difference?
+
+| Examples | Guides |
+|----------|--------|
+| **What**: Working code to copy | **How**: Step-by-step instructions |
+| **Goal**: Show implementation | **Goal**: Teach a task |
+| **Format**: Complete code samples | **Format**: Instructional steps |
+| **When to use**: Need code quickly | **When to use**: Learning workflow |
+
+**Example scenario**:
+- **Guide**: "How to Extract Entities from PDFs" - teaches the process
+- **Example**: "PDF Entity Extraction Sample" - provides working code
+
+## Sample Datasets
+
+The [Sample Data](sample-data/) section provides:
+- Pre-loaded knowledge graphs for testing
+- Sample PDFs and documents
+- Data generators for creating test data
+- Benchmark datasets
+
+Perfect for:
+- Testing your TrustGraph installation
+- Learning query patterns
+- Benchmarking performance
+- Developing and testing features
+
+## Contributing Examples
+
+Have a great example to share? We welcome contributions!
+
+See [Contributing Guidelines](../contributing/contributing) for:
+- Example submission guidelines
+- Code style requirements
+- Documentation standards
+- Licensing information
-## Learning Path
+## Quick Links
-1. Start with [Sample Data](sample-data/) to understand data formats
-2. Follow [Tutorials](tutorials/) for hands-on learning
-3. Explore [Integrations](integrations/) for real-world applications
+- **Test your setup**: Start with [Sample Data](sample-data/)
+- **Learn workflows**: See [How-to Guides](../guides/)
+- **Understand concepts**: Read the [Overview](../overview/)
+- **Deploy TrustGraph**: Follow [Getting Started](../getting-started/)
-Coming soon - comprehensive examples and tutorials!
\ No newline at end of file
diff --git a/examples/integrations/index.md b/examples/integrations/index.md
index 2fa240e..f0530d7 100644
--- a/examples/integrations/index.md
+++ b/examples/integrations/index.md
@@ -1,6 +1,5 @@
---
title: Integrations
-layout: default
parent: Examples
grand_parent: TrustGraph Documentation
---
diff --git a/examples/nlp-structured-queries.md b/examples/nlp-structured-queries.md
index 53c7a19..53497d0 100644
--- a/examples/nlp-structured-queries.md
+++ b/examples/nlp-structured-queries.md
@@ -1,5 +1,4 @@
---
-layout: default
title: NLP and Structured Query Examples
parent: Examples
nav_order: 5
diff --git a/examples/sample-data/index.md b/examples/sample-data/index.md
index 197a4fe..6916a78 100644
--- a/examples/sample-data/index.md
+++ b/examples/sample-data/index.md
@@ -1,6 +1,5 @@
---
title: Sample Data
-layout: default
parent: Examples
grand_parent: TrustGraph Documentation
---
diff --git a/examples/tutorials/index.md b/examples/tutorials/index.md
index 72b9200..0e798be 100644
--- a/examples/tutorials/index.md
+++ b/examples/tutorials/index.md
@@ -1,6 +1,5 @@
---
title: Tutorials
-layout: default
parent: Examples
grand_parent: TrustGraph Documentation
---
diff --git a/getting-started/concepts.md b/getting-started/concepts.md
index bb81101..9babb5c 100644
--- a/getting-started/concepts.md
+++ b/getting-started/concepts.md
@@ -1,6 +1,5 @@
---
title: Core Concepts
-layout: default
nav_order: 1
parent: Getting Started
grand_parent: TrustGraph Documentation
@@ -8,166 +7,226 @@ grand_parent: TrustGraph Documentation
# Core Concepts
-Understand the fundamental concepts and architecture that make TrustGraph a powerful AI agent intelligence platform.
+This page covers the essential concepts you need to understand to work with TrustGraph effectively. For a deeper dive into TrustGraph's architecture and philosophy, see the [Introduction](../overview/introduction).
-## What is TrustGraph?
-
-TrustGraph is an **Open Source Agent Intelligence Platform** that transforms AI agents from simple task executors into intelligent, contextually-aware systems. Unlike traditional AI approaches that work with isolated data points, TrustGraph creates interconnected knowledge structures that enable agents to understand relationships and context.
-
-## Core Concepts
+## Essential Terminology
-### Knowledge Graphs
+As you work with TrustGraph, you'll encounter these key terms:
-**Knowledge Graphs** are the foundation of TrustGraph's intelligence. They represent information as interconnected networks of entities and relationships, rather than isolated documents or data points.
+### Knowledge Graph
+A network of interconnected entities (people, places, concepts) and their relationships. When you load a document into TrustGraph, it's automatically converted into a knowledge graph.
-- **Entities**: People, places, concepts, or objects in your data
-- **Relationships**: How entities connect and relate to each other
-- **Context**: The meaning that emerges from understanding these connections
+**Example**: A document about a company might create entities for "Company", "CEO", "Product" and relationships like "employs" and "manufactures".
-### GraphRAG (Graph Retrieval-Augmented Generation)
+### GraphRAG
+Graph-enhanced Retrieval and Augmented Generation. When you ask TrustGraph a question, GraphRAG uses the knowledge graph structure to find relevant, contextually-connected information before generating an answer.
-**GraphRAG** is TrustGraph's advanced approach to information retrieval that goes beyond traditional RAG systems:
+**Why it matters**: GraphRAG provides more accurate answers than traditional search because it understands how information relates.
-**Traditional RAG:**
-- Retrieves similar documents based on vector similarity
-- Works with isolated pieces of information
-- Limited contextual understanding
+### Vector Embeddings
+Mathematical representations of text that enable semantic similarity search. TrustGraph creates embeddings for your documents so you can find conceptually similar content even if exact words don't match.
-**GraphRAG:**
-- Understands relationships between different pieces of information
-- Retrieves contextually relevant knowledge based on graph structure
-- Provides more accurate, nuanced responses
-- Significantly reduces AI hallucinations
+**Example**: Searching for "CEO" might also find "Chief Executive Officer" or "company leader".
-### Structured Query Processing
+### N-Triples
+The format TrustGraph uses to represent graph data. Each line shows a relationship:
+```
+