@benchcubed/today-cli 1.0.0 → 1.0.1

package/README.md

@@ -1,68 +1,178 @@
 # Today CLI - AI-Powered Developer Knowledge Platform
 
-**AWS 10,000 AIdeas Competition Entry - Workplace Efficiency Track**
+Today is an intelligent knowledge management system that transforms how developers capture, share, and discover technical knowledge. Built with AWS and powered by AI, it eliminates knowledge silos and reduces onboarding time by making expertise searchable and accessible right from your terminal.
 
-Today eliminates developer question anxiety and knowledge silos through an AI-powered CLI that captures learning instantly and connects teams with the right experts. It transforms workplace efficiency by making knowledge sharing as natural as breathing, reducing onboarding time by 70% while building psychological safety.
+## 🎯 What is Today?
 
-## 🎯 Competition Value Proposition
+Today is a CLI-first knowledge platform that:
 
-- **Eliminates question anxiety**: Developers can ask natural language questions privately before approaching human experts
-- **Measurable ROI**: 70% reduction in developer onboarding time, 50% fewer repeated questions
-- **Zero workflow disruption**: CLI-first approach keeps developers in their terminal
-- **Amazon Bedrock-powered insights**: Real-time knowledge gap detection and expert recommendations
-- **Scalable impact**: Works within AWS Free Tier, supports growing teams
+- **Captures knowledge effortlessly**: Log what you learn with simple commands or automatic git commit analysis
+- **Searches intelligently**: Ask questions in natural language and get relevant answers from your team's collective knowledge
+- **Connects you with experts**: Automatically identifies team members with specific expertise
+- **Learns from your workflow**: Integrates with git to capture learnings from code changes
+- **Provides insights**: AI-powered analytics show productivity impact and knowledge gaps
 
-## 🚀 Quick Start
+### Key Benefits
 
-### Installation
+- 70% reduction in developer onboarding time
+- Eliminate repeated questions across teams
+- Build searchable knowledge bases automatically
+- Find experts and answers without interrupting your workflow
+- Works entirely from your terminal
+
+## 🚀 Installation
+
+### For Users
+
+Install globally from npm:
+
+```bash
+npm install -g @benchcubed/today-cli
+```
+
+That's it! The `today` command is now available system-wide.
+
+### For Developers
+
+Clone and build from source:
 
 ```bash
+# Clone the repository
+git clone https://github.com/benchcubed/Today.git
+cd Today
+
 # Install dependencies
 npm install
 
 # Build the project
 npm run build
 
-# Install CLI globally (optional)
+# Link CLI locally for development
 npm link
 ```
 
-### Basic Usage
+## ⚙️ Setup
+
+### 1. Configure Your Profile
+
+```bash
+# Set up your team and user information
+today config --team my-team --user my-username
+```
+
+### 2. Authenticate (if using cloud backend)
+
+```bash
+# Authenticate with AWS Cognito
+today auth --username your-username --password your-password
+```
+
+### 3. Enable Automatic Learning Capture (Optional)
 
 ```bash
-# Capture what you learned
+# Enable git hook to capture learnings from commits
+today git-hook --enable
+```
+
+## 📖 Quick Start Guide
+
+### Capture What You Learn
+
+The simplest way to build your knowledge base:
+
+```bash
+# Log a single learning
 today learned "React useCallback should be used sparingly - only for optimized child components"
 
-# Ask natural language questions or search your knowledge base
+# Add tags for better organization
+today learned "Always use connection pooling for databases" --tags database,performance
+
+# The git hook captures learnings automatically from commits (if enabled)
+git commit -m "feat(auth): implement JWT refresh tokens"
+git push  # Learning entry created automatically!
+```
+
+### Search Your Knowledge Base
+
+Ask questions in natural language:
+
+```bash
+# Simple search
 today ask "How should I optimize React performance?"
-today ask "What's the best way to handle database connections?"
-today ask "React hooks" --author john --tags react,hooks
 
-# Additional search options
-today ask "authentication" --limit 20                    # Get more results
-today ask "database" --author jane                       # Filter by author
-today ask "testing" --tags unit-tests,integration       # Filter by tags
-today ask "performance" --no-vector                      # Use keyword search only
+# Filter by author
+today ask "database connections" --author jane
 
-# Configure the CLI
-today config --team my-team --user my-username
+# Filter by tags
+today ask "authentication" --tags security,jwt
 
-# Authenticate with AWS Cognito
-today auth --username demo-user --password DemoPass123!
+# Get more results
+today ask "testing strategies" --limit 20
 
-# View productivity stats
-today stats
+# Use keyword-only search (faster)
+today ask "error handling" --no-vector
+```
+
+### Find Team Experts
 
-# Find team experts
+Discover who knows what on your team:
+
+```bash
+# Find TypeScript experts
 today experts "TypeScript"
 
-# Get AI insights
+# Find experts in any domain
+today experts "AWS Lambda" --limit 10
+```
+
+### View Your Impact
+
+See productivity metrics and insights:
+
+```bash
+# View your learning statistics
+today stats
+
+# Get AI-powered insights about your knowledge base
 today insights
+
+# See recent learning entries
+today recent
+
+# Analyze your learning patterns
+today audit
+```
+
+### Onboarding New Team Members
+
+Help new developers get up to speed quickly:
+
+```bash
+# Interactive onboarding flow
+today onboard
+
+# Generate onboarding reports
+today onboard --report
 ```
 
-### 🎯 Automatic Learning Capture from Git Commits
+### Advanced Features
 
-Today CLI can automatically capture learning entries from your git commits! When enabled, it analyzes commits during `git push`, identifies well-structured commits, and creates comprehensive learning entries from the code changes.
+```bash
+# Manage secrets securely
+today secrets --scan          # Scan for exposed secrets
+today secrets --list          # List detected secrets
+
+# Export/import knowledge bases
+today export --format json --output backup.json
+today import --file backup.json
+
+# View productivity impact
+today impact                  # See time saved and efficiency gains
+```
+
+### 🔄 Automatic Learning Capture from Git
+
+Today can automatically capture learning entries from your git commits, turning your development workflow into a knowledge-building machine.
 
 #### Enable the Git Hook
 
@@ -79,66 +189,63 @@ today git-hook --disable
 
 #### How It Works
 
-1. **Commit Analysis**: When you push commits, the hook analyzes each commit's structure and quality
-2. **Smart Detection**: Well-structured commits (especially conventional commits like `feat:`, `fix:`, `docs:`) are identified
-3. **Context Extraction**: The hook extracts the commit message, diff, and file changes
-4. **AI Enhancement**: Uses Amazon Bedrock AI to generate comprehensive learning entries that capture:
-   - What was learned or implemented
-   - Why the change was made
-   - Technical patterns and best practices
-   - Important considerations and gotchas
-   - Future applications of this knowledge
-5. **Automatic Submission**: Learning entries are automatically submitted to your team's knowledge base
+1. **Commit Analysis**: Analyzes each commit's structure and quality during push
+2. **Smart Detection**: Identifies well-structured commits (especially conventional commits)
+3. **Context Extraction**: Extracts commit message, diff, and file changes
+4. **AI Enhancement**: Uses Amazon Bedrock AI to generate comprehensive learning entries
+5. **Automatic Submission**: Learning entries are automatically submitted to your knowledge base
 
 #### Best Practices
 
-For best results, use **conventional commit** format:
+Use **conventional commit** format for best results:
 
 ```bash
-# Examples of commits that generate great learning entries:
 git commit -m "feat(auth): implement JWT token refresh mechanism"
 git commit -m "fix(api): resolve race condition in database connection pool"
 git commit -m "refactor(utils): extract validation logic into reusable functions"
 git commit -m "docs(readme): add section on error handling patterns"
 ```
 
-The git hook won't block your push if learning capture fails - your development flow stays uninterrupted!
+The git hook won't block your push if learning capture fails - your workflow stays uninterrupted!
 
 
 ## 🏗️ Architecture
 
-### Competition-Optimized AWS Stack
+### AWS Technology Stack
 
-- **AWS Lambda** (1M requests/month) - AI processing and backend logic
-- **Amazon API Gateway** (1M calls/month) - RESTful API for CLI and web interface
-- **Amazon RDS PostgreSQL** (db.t3.micro, 20GB) - Structured knowledge storage
-- **Amazon DynamoDB** (25GB) - Real-time knowledge graph caching
-- **Amazon S3** (5GB) - Web interface hosting and demo data
-- **Amazon CloudFront** - Global CDN for fast web interface delivery
-- **AWS Cognito** (50K MAU) - User authentication and team management
+- **AWS Lambda** - AI processing and backend logic
+- **Amazon API Gateway** - RESTful API for CLI and web interface
+- **Amazon RDS PostgreSQL** - Structured knowledge storage
+- **Amazon DynamoDB** - Real-time knowledge graph caching
+- **Amazon S3** - Web interface hosting and file storage
+- **Amazon CloudFront** - Global CDN for fast content delivery
+- **AWS Cognito** - User authentication and team management
+- **Amazon Bedrock** - AI-powered knowledge enhancement and semantic search
 
 ### Technology Stack
 
 - **TypeScript** - Type-safe development with modern tooling
 - **Commander.js** - Robust CLI framework
-- **Amazon Bedrock** - AI-powered knowledge enhancement
+- **Amazon Bedrock** - AI-powered knowledge processing
+- **PostgreSQL** - Reliable relational database for knowledge storage
+- **Vector Embeddings** - Semantic search with 1024-dimension Titan embeddings
 
-## 🧪 Testing Strategy
+## 🧪 Testing
 
-### Property-Based Testing with fast-check
+### Run Tests
 
 ```bash
 # Run all tests
 npm test
 
-# Run property-based tests specifically
+# Run property-based tests
 npm run test:property
 
 # Watch mode for development
 npm run test:watch
 ```
 
-### Competition Correctness Properties
+### Test Coverage
 
 The system validates 22 correctness properties including:
 - Learning entry creation integrity
@@ -147,7 +254,7 @@ The system validates 22 correctness properties including:
 - Knowledge graph structure integrity
 - Productivity impact measurement
 
-## 🚀 AWS Deployment
+## 🚀 Deploying Your Own Instance
 
 ### Prerequisites
 
@@ -160,7 +267,7 @@ brew install terraform  # macOS
 aws configure
 ```
 
-### Deploy Competition Stack (One Command!)
+### One-Command Deployment
 
 ```bash
 # Bundle Lambda functions and deploy infrastructure
@@ -177,14 +284,14 @@ That's it! The deploy command will:
 If you prefer to run steps individually:
 
 ```bash
-# 1. Bundle Lambda functions (tree shaking + minification)
+# 1. Bundle Lambda functions
 npm run bundle
 
 # 2. Deploy with Terraform
 cd infrastructure && terraform apply
 ```
 
-### Environment Variables
+### Environment Configuration
 
 The Lambda functions automatically receive environment variables from Terraform including:
 - DynamoDB table names
@@ -194,14 +301,16 @@ The Lambda functions automatically receive environment variables from Terraform
 
 No manual environment variable setup needed!
 
-## 📊 Competition Metrics
+## 📊 Impact Metrics
 
-- **Total time saved**: 2,847 minutes across all teams
-- **Onboarding acceleration**: 71% average improvement
-- **ROI**: 230% return on investment
-- **Knowledge reuse rate**: 78-85% across teams
+Today delivers measurable productivity improvements:
 
-### Before/After Comparison
+- **70% reduction** in developer onboarding time
+- **67% reduction** in daily search time
+- **70% fewer** repeated questions
+- **458% increase** in knowledge sharing
+
+### Real-World Results
 
 | Metric | Before Today | After Today | Improvement |
 |--------|-------------|-------------|-------------|
@@ -210,27 +319,6 @@ No manual environment variable setup needed!
 | Repeated Questions | 23/week | 7/week | 70% reduction |
 | Knowledge Sharing | 12/month | 67/month | 458% increase |
 
-## 🎯 Competition Timeline
-
-- **Week 1-2**: Core CLI and knowledge capture ✅
-- **Week 3-4**: AI-powered expert discovery and insights
-- **Week 5-6**: Interactive knowledge graph and analytics dashboard
-- **Week 7**: Competition polish, metrics collection, and submission
-
-## 🏆 Competition Success Metrics
-
-### Technical Innovation
-- Serverless architecture showcasing 6+ AWS services
-- AI-powered expert discovery and knowledge insights
-- Real-time knowledge graph visualization
-- Cloud-based CLI with secure authentication
-
-### Workplace Efficiency Impact
-- Measurable ROI tracking with before/after comparisons
-- Onboarding time reduction metrics
-- Question anxiety elimination through private knowledge search
-- Expert connection facilitation and success tracking
-
 ## 📚 Development
 
 ### Project Structure
@@ -239,7 +327,9 @@ No manual environment variable setup needed!
 today-cli/
 ├── src/
 │   ├── cli.ts              # Main CLI entry point
-│   ├── lambda/             # Lambda function handlers
+│   ├── commands/           # CLI command implementations
+│   ├── services/           # Core business logic
+│   ├── lambda/             # AWS Lambda function handlers
 │   ├── config/             # Configuration management
 │   ├── database/           # PostgreSQL schema and migrations
 │   └── types/              # TypeScript type definitions
@@ -257,13 +347,13 @@ today-cli/
 ### Available Scripts
 
 #### Core Commands
-- `npm run bundle` - Bundle Lambda functions with esbuild (tree shaking + minification)
-- `npm run deploy` - Bundle and deploy backend infrastructure (one command!)
-- `npm run deploy:backend` - Explicit backend deployment
+- `npm run bundle` - Bundle Lambda functions with esbuild
+- `npm run deploy` - Bundle and deploy full infrastructure
+- `npm run deploy:backend` - Deploy backend infrastructure only
 - `npm run deploy:web` - Deploy web frontend to S3/CloudFront
 
 #### Development
-- `npm run build` - Build TypeScript to JavaScript (for CLI)
+- `npm run build` - Build TypeScript to JavaScript
 - `npm run dev` - Run CLI in development mode
 - `npm test` - Run test suite
 - `npm run lint` - Lint TypeScript code
@@ -272,25 +362,24 @@ today-cli/
 The build process uses **esbuild** for optimal Lambda bundling:
 - **Tree Shaking**: Removes unused code (~90% size reduction)
 - **Minification**: Reduces bundle size for faster cold starts
-- **Parallel Builds**: All 7 Lambda functions build simultaneously
+- **Parallel Builds**: All Lambda functions build simultaneously
 - **External Dependencies**: AWS SDK excluded (provided by Lambda runtime)
 
 ## 🤝 Contributing
 
-This is a competition entry for AWS 10,000 AIdeas. The project showcases:
+Contributions are welcome! This project showcases:
 
-1. **Workplace Efficiency**: Measurable productivity improvements
-2. **AWS Integration**: Comprehensive use of AWS services within Free Tier
-3. **AI Innovation**: Amazon Bedrock-powered knowledge enhancement
-4. **Developer Experience**: CLI-first, cloud-based design
+1. **AI-Powered Knowledge Management**: Intelligent capture and retrieval of technical knowledge
+2. **Comprehensive AWS Integration**: Serverless architecture using modern AWS services
+3. **Developer Experience**: CLI-first design that fits naturally into developer workflows
+4. **Measurable Impact**: Productivity improvements backed by real metrics
 
 ## 📄 License
 
-MIT License - Built for AWS 10,000 AIdeas Competition
+MIT License
 
 ---
 
-**Competition Submission**: January 21, 2026  
-**Track**: Workplace Efficiency  
-**AWS Services**: Lambda, API Gateway, RDS, DynamoDB, S3, CloudFront, Cognito, Bedrock  
-**AI Integration**: Amazon Bedrock with Claude/Llama models for natural language processing and expert matching
+**GitHub**: [benchcubed/Today](https://github.com/benchcubed/Today)  
+**npm**: [@benchcubed/today-cli](https://www.npmjs.com/package/@benchcubed/today-cli)  
+**Built with**: AWS Lambda, API Gateway, RDS, DynamoDB, S3, CloudFront, Cognito, Amazon Bedrock

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@benchcubed/today-cli",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "AI-powered developer knowledge platform for AWS 10,000 AIdeas Competition",
   "main": "dist/index.js",
   "bin": {