update documentation and descriptions

lxsaah · lxsaah · commit cd7c4b04bddf · 2025-11-07T11:28:38.000Z
diff --git a/.github/chatmodes/architecture.chatmode.md b/.github/chatmodes/architecture.chatmode.md
@@ -59,7 +59,9 @@ You are a software architect for AimDB. Focus on:
 - **Event sourcing**: Immutable event log as source of truth
 - **CQRS**: Separate read/write models for performance
 - **Saga patterns**: Distributed transaction management
-- **Event streaming**: Real-time data processing pipelines
+- **Multi-tier caching**: Device-edge-cloud consistency
+- **Event streaming**: Data processing pipelines
+- **Command-control**: Bidirectional device control
 
 ### Microservices Considerations
 - **Service boundaries**: Domain-driven design principles
diff --git a/.github/chatmodes/embedded.chatmode.md b/.github/chatmodes/embedded.chatmode.md
@@ -14,7 +14,7 @@ You are an expert in embedded Rust development for AimDB. Focus on:
 - **Memory-efficient implementations** with minimal allocations
 - **Lock-free data structures** suitable for resource-constrained environments
 - **Power consumption considerations** for battery-powered devices
-- **Real-time constraints** and deterministic behavior
+- **Low-latency constraints** and deterministic behavior
 - **Integration with hardware peripherals** and sensors
 - **Optimizations for specific MCU architectures** (ARM Cortex-M, RISC-V)
 - **Stack usage analysis** and memory safety in embedded contexts
@@ -36,7 +36,7 @@ You are an expert in embedded Rust development for AimDB. Focus on:
 
 ## Performance Priorities
 1. **Memory usage** (RAM/Flash optimization)
-2. **Real-time determinism** (predictable execution times)
+2. **Deterministic execution** (predictable execution times)
 3. **Power efficiency** (low-power modes, sleep states)
 4. **Code size** (fitting within flash constraints)
 5. **CPU efficiency** (optimized algorithms for limited processing power)
diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md
@@ -1,7 +1,7 @@
 # GitHub Copilot Instructions for AimDB
 
 ## Project Status & Quick Start
-AimDB is an async, in-memory database for real-time data synchronization across **MCU → edge → cloud** environments, targeting <50ms reactivity. The core architecture is fully implemented and functional.
+AimDB is an async, in-memory database for data synchronization across **MCU → edge → cloud** environments, targeting <50ms reactivity. The core architecture is fully implemented and functional.
 
 **Implementation Status:**
 - ✅ **Core Database** - Type-safe records with optimized TypeId lookups
@@ -38,7 +38,7 @@ When working with running AimDB instances, **always prefer using the MCP tools**
 - `mcp_aimdb_get_record` - Get current value of a record
 - `mcp_aimdb_set_record` - Set value of writable records
 - `mcp_aimdb_query_schema` - Infer JSON Schema from record values
-- `mcp_aimdb_subscribe_record` - Subscribe to real-time updates
+- `mcp_aimdb_subscribe_record` - Subscribe to live updates
 - `mcp_aimdb_unsubscribe_record` - Unsubscribe from updates
 - `mcp_aimdb_get_instance_info` - Get server version and capabilities
 - `mcp_aimdb_list_subscriptions` - List active subscriptions
@@ -74,7 +74,7 @@ mcp_aimdb_set_record(
 - ✅ Inspecting running AimDB instances
 - ✅ Testing record schemas and values
 - ✅ Debugging database state
-- ✅ Monitoring real-time data
+- ✅ Monitoring live data
 - ✅ Validating record configurations
 - ✅ Quick data exploration
 
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -47,14 +47,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **MCP Server** (`aimdb-mcp`): LLM-powered introspection and debugging
   - Discover running AimDB instances
   - Query record values and schemas
-  - Subscribe to real-time updates
+  - Subscribe to live updates
   - Set writable record values
   - JSON Schema inference from record values
   - Notification persistence to JSONL files
 - **CLI Tool** (`aimdb-cli`): Command-line interface (skeleton)
   - Instance discovery and management commands
   - Record inspection capabilities
-  - Real-time watch functionality
+  - Live watch functionality
 - **Client Library** (`aimdb-client`): Reusable connection and discovery logic
   - Unix domain socket communication
   - AimX v1 protocol implementation
@@ -88,7 +88,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Dev container setup for consistent development environment
 
 ### Design Goals Achieved
-- ✅ Sub-50ms latency for real-time synchronization
+- ✅ Sub-50ms latency for data synchronization
 - ✅ Lock-free buffer operations
 - ✅ Cross-platform support (MCU → edge → cloud)
 - ✅ Type safety with zero-cost abstractions
@@ -123,7 +123,7 @@ AimDB v0.1.0 establishes the foundational architecture for async, in-memory data
 **Highlights:**
 - 🚀 Dual runtime support: Works on both standard library (Tokio) and embedded (Embassy)
 - 🔒 Type-safe record system eliminates runtime string lookups
-- 📦 Three buffer types cover most real-time data patterns
+- 📦 Three buffer types cover most data patterns
 - 🔌 MQTT connector works in both std and `no_std` environments
 - 🤖 MCP server enables LLM-powered introspection
 - ✅ 27+ core tests, comprehensive CI/CD, security auditing
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -4,7 +4,9 @@ Thank you for your interest in contributing to AimDB! This document provides gui
 
 ## Project Overview
 
-AimDB is an async, in-memory database designed for real-time data synchronization across **MCU → edge → cloud** environments, targeting <50ms reactivity. The project is built in Rust and supports multiple platform targets from embedded microcontrollers to cloud deployments.
+---
+
+AimDB is an async, in-memory database designed for data synchronization across **MCU → edge → cloud** environments, targeting <50ms reactivity. The project is built in Rust and supports multiple platform targets from embedded microcontrollers to cloud deployments.
 
 ## Getting Started
 
@@ -204,12 +206,9 @@ cargo test test_name --features tokio-runtime
 Use clear, descriptive commit messages:
 
 ```
-add async stream handler for real-time data sync
+add async stream handler for data sync
 
-- Implement lock-free ring buffer for <50ms latency
-- Add feature flag for embedded targets
-- Include comprehensive tests and examples
-```
+Implements bidirectional streaming between embedded and cloud layers
 
 ## Project Structure
 
diff --git a/Cargo.toml b/Cargo.toml
@@ -26,8 +26,8 @@ authors = ["AimDB Team <team@aimdb.dev>"]
 license = "Apache-2.0"
 repository = "https://github.com/aimdb-dev/aimdb"
 homepage = "https://aimdb.dev"
-description = "Async in-memory database for real-time synchronization across MCU → edge → cloud environments"
-keywords = ["database", "async", "embedded", "real-time", "sync"]
+description = "Async in-memory database for data synchronization across MCU → edge → cloud environments"
+keywords = ["database", "async", "embedded", "sync", "iot"]
 categories = ["database-implementations", "embedded", "asynchronous"]
 
 [workspace.dependencies]
diff --git a/README.md b/README.md
@@ -16,7 +16,7 @@
 
 > **One codebase. Any hardware. Always in sync.**
 
-AimDB is an **async, in-memory database** for real-time data synchronization across **MCU → edge → cloud** — without internal brokers or vendor lock-in. Built in Rust with `no_std` support for embedded systems.
+AimDB is an **async, in-memory database** for data synchronization across **MCU → edge → cloud** — without internal brokers or vendor lock-in. Built in Rust with `no_std` support for embedded systems.
 
 ---
 
@@ -25,7 +25,7 @@ AimDB is an **async, in-memory database** for real-time data synchronization acr
 Modern IoT stacks are fragmented:
 - Multiple brokers/databases to sync MCU, edge, and cloud
 - Device-specific integrations that make hardware swaps risky
-- Batch-oriented pipelines that miss real-time insights
+- Batch-oriented pipelines that miss low-latency insights
 
 **AimDB simplifies this:**
 - **Fast**: Lock-free buffers + async transforms for <50ms reactivity
@@ -211,7 +211,7 @@ Single slot with overwrite. Latest command wins.
 - Kafka connector (std environments)
 
 **📋 Planned:**
-- DDS connector for real-time systems
+- DDS connector for low-latency systems
 - HTTP/REST bridge
 - Advanced observability and metrics
 - Multi-instance clustering
diff --git a/aimdb-core/Cargo.toml b/aimdb-core/Cargo.toml
@@ -5,7 +5,7 @@ edition.workspace = true
 license.workspace = true
 repository.workspace = true
 homepage.workspace = true
-description = "Core database engine for AimDB - async in-memory storage with real-time synchronization"
+description = "Core database engine for AimDB - async in-memory storage with data synchronization"
 keywords.workspace = true
 categories.workspace = true
 build = "build.rs"
diff --git a/aimdb-core/README.md b/aimdb-core/README.md
@@ -1,10 +1,10 @@
 # aimdb-core
 
-Core database engine for AimDB - async in-memory storage with real-time synchronization.
+Core database engine for AimDB - async in-memory storage with data synchronization.
 
 ## Overview
 
-`aimdb-core` provides the foundational database engine for AimDB, designed for real-time data synchronization across **MCU → edge → cloud** environments with low-latency synchronization.
+`aimdb-core` provides the foundational database engine for AimDB, designed for data synchronization across **MCU → edge → cloud** environments with low-latency synchronization.
 
 **Key Features:**
 - **Type-Safe Records**: `TypeId`-based routing eliminates string keys and enables compile-time safety
diff --git a/aimdb-core/src/database.rs b/aimdb-core/src/database.rs
@@ -1,7 +1,7 @@
-//! AimDB Database Implementation
+//! Core database implementation
 //!
-//! This module provides the unified database implementation for AimDB, supporting async
-//! in-memory storage with type-safe records and real-time synchronization across
+//! `AimDb` is the central coordination point for AimDB, managing type-safe
+//! in-memory storage with type-safe records and data synchronization across
 //! MCU → edge → cloud environments.
 
 use crate::{AimDb, DbError, DbResult, RuntimeAdapter, RuntimeContext};
diff --git a/aimdb-core/src/lib.rs b/aimdb-core/src/lib.rs
@@ -1,6 +1,8 @@
 //! AimDB Core Database Engine
 //!
-//! Type-safe, async in-memory database for real-time data synchronization
+//! # aimdb-core
+//!
+//! Type-safe, async in-memory database for data synchronization
 //! across MCU → edge → cloud environments.
 //!
 //! # Architecture
diff --git a/aimdb-core/src/remote/handler.rs b/aimdb-core/src/remote/handler.rs
@@ -873,7 +873,7 @@ where
 
 /// Handles record.subscribe method
 ///
-/// Subscribes to real-time updates for a record.
+/// Subscribes to live updates for a record.
 ///
 /// # Arguments
 /// * `db` - Database instance
diff --git a/aimdb-sync/Cargo.toml b/aimdb-sync/Cargo.toml
@@ -6,7 +6,7 @@ authors = ["AimDB Team"]
 license = "MIT OR Apache-2.0"
 description = "Synchronous API wrapper for AimDB - blocking operations for async database"
 repository = "https://github.com/aimdb-dev/aimdb"
-keywords = ["database", "sync", "blocking", "real-time"]
+keywords = ["database", "sync", "blocking", "iot"]
 categories = ["database"]
 
 [dependencies]
diff --git a/aimdb-sync/src/lib.rs b/aimdb-sync/src/lib.rs
@@ -176,7 +176,7 @@
 //!
 //! - **Overhead**: ~100-500μs per operation vs pure async (channel + context switch)
 //! - **Throughput**: Limited by channel capacity (default: 100 items)
-//! - **Latency**: Excellent for <50ms target, not suitable for hard real-time
+//! - **Latency**: Excellent for <50ms target, not suitable for hard low-latency requirements
 //!
 //! ## Error Handling
 //!
diff --git a/docs/design/003-M1_buffer_usage_guide.md b/docs/design/003-M1_buffer_usage_guide.md
@@ -31,10 +31,10 @@ This guide explains **when to use each buffer type**, **how to configure them**,
 #### When to Use
 
 ```
-📊 Sensor Data Streaming
-   → 100 Hz temperature readings
-   → Multiple analysis pipelines (real-time, historical, ML)
-   → Some consumers may lag, but latest data matters most
+**Example**: Temperature sensor → Multiple consumers
+   → Edge processor (real-time display)
+   → Cloud logger (historical storage)
+   → ML pipeline (real-time analysis, historical training)
 
 🔍 System Event Monitoring  
    → Application events, errors, warnings
diff --git a/docs/design/009-M4-mcp-integration.md b/docs/design/009-M4-mcp-integration.md
@@ -56,7 +56,10 @@ From implementing **AimX v1** protocol and the **aimdb-cli** tool, we gained cri
 2. **Unix Domain Sockets**: Low overhead, OS-level security, no network exposure
 3. **Discovery Pattern**: Scanning `/tmp` and `/var/run/aimdb` for `.sock` files
 4. **Request/Response Model**: Clean separation of concerns, easy to reason about
-5. **Subscription Pattern**: Efficient for real-time monitoring (event funnel architecture)
+4. **Connection Management**: Automatic reconnection on failures
+5. **Subscription Pattern**: Efficient for monitoring (event funnel architecture)
+
+---
 6. **Security Model**: Read-only default with explicit write permissions per record
 7. **Connection Handling**: Tokio-based async I/O, bounded queues prevent backpressure
 
@@ -176,7 +179,7 @@ aimdb-mcp/
 │   │   ├── mod.rs
 │   │   ├── instance.rs      # Instance discovery tools
 │   │   ├── record.rs        # Record operations (list, get, set)
-│   │   └── subscription.rs  # Real-time monitoring tools
+│   │   └── subscription.rs  # Live monitoring tools
 │   ├── resources/           # MCP resource providers
 │   │   ├── mod.rs
 │   │   ├── schemas.rs       # Record schema resources
@@ -617,7 +620,7 @@ instructions: |
 - [ ] Connection failures are handled gracefully
 - [ ] 80%+ code coverage for tools
 
-### Phase 3: Real-time Monitoring (Week 3)
+### Phase 3: Live Monitoring (Week 3)
 
 **Goal**: Enable subscription-based monitoring.
 
@@ -766,7 +769,7 @@ rate_limit = 100
 
 - **Tracing Integration**: Distributed tracing for tool invocations
 - **Metrics Export**: Prometheus metrics for MCP server performance
-- **Dashboard Resource**: Real-time dashboard data in MCP resource
+- **Dashboard Resource**: Live dashboard data in MCP resource
 - **Alerting Templates**: LLM-assisted alert rule generation
 
 ### v2.0 - Advanced Workflows
diff --git a/docs/design/010-M4-mcp-notification-memory.md b/docs/design/010-M4-mcp-notification-memory.md
@@ -9,7 +9,10 @@
 3. ❌ LLM has no way to access notification history
 4. ❌ LLM must poll via `get_record` instead of using subscription data
 
-**Impact**: Real-time monitoring, alerting, and event-driven workflows are impossible for LLMs despite having a working notification system.
+## Problem Statement
+
+**Status**: Implemented ✅  
+**Impact**: Monitoring, alerting, and event-driven workflows are impossible for LLMs despite having a working notification system.
 
 ## Proposed Solution: MCP Notification Memory
 
@@ -125,7 +128,7 @@ pub struct NotificationEntry {
 - ✅ **Easy cleanup** - `rm 2025-10-*` to delete old month
 - ✅ **Human-readable** filenames for debugging
 - ✅ **Append-only** (no corruption risk)
-- ✅ **Can be tailed** for real-time monitoring
+- ✅ **Can be tailed** for live monitoring
 
 **File Rotation Strategy**:
 - **Daily rotation**: New file created automatically for each date
@@ -508,7 +511,7 @@ LLM: (Reads error, consults schema, asks user)
    ```rust
    Tool {
        name: "subscribe_record".to_string(),
-       description: "Subscribe to real-time updates for a specific record.\n\n\
+       description: "Subscribe to live updates for a specific record.\n\n\
            ⚠️  IMPORTANT: You MUST ask the user how many samples to collect before subscribing.\n\
            Unlimited subscriptions can fill disk space.\n\n\
            Behavior:\n\
@@ -868,7 +871,7 @@ The MCP Notification Memory feature has been successfully implemented and tested
 
 ✅ **Verified Features**:
 - Files created at `~/.aimdb-mcp/notifications/{date}__{record}.jsonl`
-- Real-time notification capture and persistence
+- Live notification capture and persistence
 - Proper JSONL format with timestamp, value, and sequence
 - File sanitization and error handling
 - LLM-friendly analysis (demonstrated with mean/max calculations)
diff --git a/docs/index.html b/docs/index.html
@@ -114,10 +114,10 @@
     <h1>AimDB Documentation</h1>
 
     <div class="intro">
-        <p><strong>AimDB</strong> is an async, in-memory database designed for real-time data synchronization across MCU
+        <p><strong>AimDB</strong> is an async, in-memory database designed for data synchronization across MCU
             → edge → cloud environments. Built with Rust for millisecond-level reactivity and platform portability.</p>
         <p><span class="badge">Async-First</span> <span class="badge">Lock-Free</span> <span
-                class="badge">Cross-Platform</span> <span class="badge">Real-Time</span></p>
+                class="badge">Cross-Platform</span> <span class="badge">Low-Latency</span></p>
     </div>
 
     <h2>Platform-Specific Documentation</h2>
diff --git a/examples/remote-access-demo/README.md b/examples/remote-access-demo/README.md
@@ -90,8 +90,7 @@ echo '{"version":"1.0","client":"test"}' | socat - UNIX-CONNECT:/tmp/aimdb-demo.
 ## Next Steps
 
 Future enhancements will add:
-- `record.get` - Read current value of a record
-- `record.subscribe` - Stream real-time updates
-- `record.unsubscribe` - Stop streaming
-- Authentication with tokens
-- Read-write mode with `record.set`
+- `record.get` - Get current value
+- `record.set` - Set writable records
+- `record.subscribe` - Stream live updates
+- `instance.shutdown` - Graceful shutdown
diff --git a/tools/aimdb-cli/README.md b/tools/aimdb-cli/README.md
@@ -8,7 +8,7 @@ The AimDB CLI is a thin client over the AimX v1 remote access protocol, providin
 - Discovering running AimDB instances
 - Listing and inspecting records
 - Getting current record values
-- Watching records in real-time
+- Watching records for live updates
 - Setting writable record values
 
 ## Installation
@@ -70,7 +70,7 @@ Example output:
 }
 ```
 
-### 4. Watch a Record in Real-Time
+### 4. Watch a Record for Live Updates
 
 ```bash
 aimdb watch server::Temperature
@@ -173,7 +173,7 @@ Options:
 ### Watch Command
 
 #### `watch`
-Watch a record in real-time, displaying updates as they arrive.
+Watch a record for live updates, displaying updates as they arrive.
 
 ```bash
 aimdb watch <RECORD> [OPTIONS]
diff --git a/tools/aimdb-cli/src/commands/watch.rs b/tools/aimdb-cli/src/commands/watch.rs
@@ -1,4 +1,4 @@
-//! Watch Command - Real-time Record Monitoring
+//! Watch Command - Live Record Monitoring
 
 use crate::error::CliResult;
 use crate::output::live;
@@ -7,7 +7,7 @@ use aimdb_client::discovery::find_instance;
 use clap::Args;
 use tokio::signal;
 
-/// Watch a record in real-time
+/// Watch a record for live updates
 #[derive(Debug, Args)]
 pub struct WatchCommand {
     /// Record name to watch
diff --git a/tools/aimdb-mcp/README.md b/tools/aimdb-mcp/README.md
diff --git a/tools/aimdb-mcp/src/prompts/mod.rs b/tools/aimdb-mcp/src/prompts/mod.rs
diff --git a/tools/aimdb-mcp/src/server.rs b/tools/aimdb-mcp/src/server.rs
diff --git a/tools/aimdb-mcp/src/tools/subscription.rs b/tools/aimdb-mcp/src/tools/subscription.rs
