@bonginkan/maria/README.md

MARIA OS v5.9.5 – Self-Evolving Organizational Intelligence OS | Speed Improvement Phase 3: LLM Optimization + Command Refactoring | Performance Measurement + Run Evidence System | Zero ESLint/TypeScript Errors | 人とAIが役割を持ち、学び、進化し続けるための仕事のOS | GraphRAG ×

# MARIA - AI Development Platform v5.9.5

[![npm version](https://img.shields.io/npm/v/@bonginkan/maria.svg)](https://www.npmjs.com/package/@bonginkan/maria)
[![License](https://img.shields.io/badge/license-Multi--tier-blue.svg)](LICENSE)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.3.3-blue)](https://www.typescriptlang.org/)
[![Node](https://img.shields.io/badge/Node-20.10.0+-green)](https://nodejs.org/)
[![Commands](https://img.shields.io/badge/Commands-166-success)](docs/COMMANDS.md)
[![Build](https://img.shields.io/badge/Build-Passing-brightgreen)](docs/BUILD_STATUS.md)
[![Ready](https://img.shields.io/badge/Ready-100%25-brightgreen)](docs/ACHIEVEMENT_REPORT_20250902.md)

> **Enterprise-grade AI development platform with 100% command availability and comprehensive fallback support**

## 🚀 What's New in v5.9.5 (January, 2026)

### 📝 Daily Blogs × Firestore (Ops SSOT)
- **Daily blog generation**: Added a daily generator script and workflow for producing 3 drafts/day.
- **Markdown normalization**: Hardened normalization so generated posts stay consistent and publish-safe.
- **Firestore sync hardening**: Improved error handling and integration for blog draft syncing.

### ⚡ Performance Measurement & Devtools (Phase 3)
- **LLM call measurement**: Instrumentation for measuring LLM call performance and budgets.
- **Command routing & streaming improvements**: Faster routing paths and more resilient streaming behavior.
- **Evidence collection**: Added tooling for collecting run evidence and performance measurement artifacts.

### 🏥 Doctor vNext + Universe Accumulation
- **Doctor command improvements**: Expanded Doctor implementation and introduced a next-gen report format.
- **Doctor Report vNext schema**: Added a dedicated schema for the new report contract.
- **Universe Accumulation API**: Implemented Express handlers/routes plus unit tests for accumulation primitives.

### 🧭 /universe UX & Documentation
- **Better help + quickstart tips**: Expanded `/universe` help and start-screen guidance.
- **Less friction by default**: Reduced required org/name inputs up-front while keeping strict guidance when needed.
- **Docs consistency**: Standardized terminology and improved English documentation coverage.

### 🛡️ Quality Gate & Reliability
- **Typecheck gate alignment**: Standardized `tsc --noEmit` usage and fixed regressions (unknown/property mismatch).
- **Auto-dev safety**: Stricter target validation and English-only policy support to prevent unintended edits.
- **UX stability**: More robust spinner/session fallback behavior and improved request tracking.

## 🚀 What's New in v5.5.5 (December, 2025)

### 🧬 Evolve (2nd Wave) + Universe OS POC Enhancements
- **Service upgrades**: Enhanced delivery ops, governance, boundary engine, and core orchestrator services.
- **Security baseline**: Added a dedicated security service (`src/services/security.ts`).
- **Decision OS & provider refinements**: Improved audit messaging, quota messaging, and provider configuration.

### 📦 Build Outputs & Manifest
- **READY manifest refresh**: Updated the READY manifest and rebuilt `dist-lib` outputs.
- **Doctor/Doc Intel updates**: Refinements across Doctor graph and document intelligence workflows.

## 🚀 What's New in v5.3.5 (December, 2025)

### 🧠 Git Intelligence Layer (NEW)
- **Implementation completed**: Automatically extracts dev themes, developer intent, and core files from Git repos, then wires evidence-backed routing to Doctor/Coder.
- **Safe read-only Git operations**: allowlist-based safe git command execution (no mutation operations).
- **Commit index**: SSOT-ifies commit history via incremental indexing (lock + manifest + ndjson).
- **Theme extraction**: Extracts development themes from recent commits (LLM on/off; falls back to hotspots when LLM is unavailable).
- **Intent inference**: Infers developer intent from worktree/commits (deterministic markers; ClassifierSpec-aligned).
- **Auto-routing**: Routes to Doctor/Coder based on riskTier and evidence (MARIA OS Foundation TaskSpec format).

**Usage:**
```bash
/git wire                    # Initialize Git Intelligence Layer
/git index update --since 14d  # Update commit index
/git intent now --llm on      # Infer current developer intent
/git theme recent --llm on    # Extract recent development themes
/git route auto              # Auto-route to Doctor/Coder
```

**Spec**: `docs/architecture/git/git-intelligence-layer.implementation-spec.v1.1.md`

### 🏗️ MARIA OS Foundation Quality Standards
- **Foundation quality spec v1.0 implemented**: Foundation system implemented per the quality spec, providing the backbone for governance, reproducibility, safety, observability, and cost control.
- **Automated ADR requirement detection**: Automatically determines ADR requirements based on PR labels and file paths; runs via GitHub Actions on PR creation.
- **Knowledge pack expansion**: Added implementation examples, troubleshooting guides, and ADR requirement guidance; also wired into MARIA OS Brain.
- **Acceptance tests S1–S5**: Implemented tests for five scenarios (low-risk auto-exec, high-risk approval gate, forbidden operation blocking, safe-stop on tool failures, isolation verification).

### 📚 Akashic & Universe OS
- **Akashic integration completed**: The Document Intelligence portal workflow is now integrated end-to-end for production usage.
- **Universe OS implementation completed**: Delivery and distribution flows were stabilized and aligned for repeatable runs.

### ☁️ Universe Deploy (GCP / per-tenant project: reproducible)
Operational model: one GCP project per tenant, and **reproducible Universe deploys via digest pinning (`image@sha256`)**:
- **Runbook (SSOT)**: `docs/06-operations/tenant-onboarding.gcp.universe-drive-style.runbook.md`
- **Script (single entrypoint)**: `scripts/deploy-tenant-universe.sh`

#### ✅ Execution log (successful example)

Tenant onboarding deploy completed successfully.

- **Deploy success (all 3 Universe services)**:
  - **Management OS**: `https://maria-universe-tenant-bonginkan-dev-management-os-i227ftjidq-an.a.run.app`
  - **Decision OS**: `https://maria-universe-tenant-bonginkan-dev-decision-os-r-i227ftjidq-an.a.run.app`
  - **Universal Analysis**: `https://maria-universe-tenant-bonginkan-dev-universal-ana-i227ftjidq-an.a.run.app`
- **Git work completed**:
  - ✅ All changes committed & pushed
  - ✅ Added a success report to PR #276
  - ✅ Total: 17 files, +2,911 / -2,571 lines
- **Key improvements**:
  - Tenant onboarding automation script (217 lines)
  - Cloud Build improvements (memory limits, digest acquisition strategy)
  - TypeScript typecheck budget management system
  - CI/CD automation improvements
  - Database optimizations

#### ✅ Deploy verification tests (14/14 passed; 100% success rate)

**Test date**: 2026-01-05
**Test script**: `scripts/test-universe-deployment.sh`
**Test report**: `docs/reports/universe-deployment-test-20260105.md`

**Three Universe services tested**:

1. **Management OS** ✅
   - URL: https://maria-universe-tenant-bonginkan-dev-management-os-i227ftjidq-an.a.run.app
   - Response time: 94ms
   - Status: healthy

2. **Decision OS** ✅
   - URL: https://maria-universe-tenant-bonginkan-dev-decision-os-r-i227ftjidq-an.a.run.app
   - Response time: 106ms
   - Status: healthy

3. **Universal Analysis** ✅
   - URL: https://maria-universe-tenant-bonginkan-dev-universal-ana-i227ftjidq-an.a.run.app
   - Response time: 105ms
   - Status: healthy

**Test cases executed**:
- ✅ Health check endpoint (200 OK for all services)
- ✅ Response time validation (avg <= 100ms; far below the 5s goal)
- ✅ Error handling (returns 404 correctly)
- ✅ Service independence (concurrent access test succeeded)
- ✅ Concurrency (200 OK for all 3 services concurrently)
- ✅ Lightweight load test (10 requests per service; all succeeded)

### ⌛ Interactive CLI Progress (UX)
- **Improved progress feedback**: Command progress indicators behave more consistently across interactive environments and stop cleanly when results are printed.
- **Better terminal readability**: Progress text styling was adjusted for clearer visibility on both dark and light themes.

### 📊 Usage & Plan Consistency
- **Aligned plan display with live usage**: Account/usage views now prefer the same source-of-truth so plan labels and quota numbers don't drift.

## 🚀 What's New in v5.3.4 (December, 2025)

### 🌐 Playground & Enterprise Quotas (LP)
- **Server-side key resolution**: Provider API keys can be resolved securely on the server (Secret Manager first, environment fallback), keeping secrets out of client code.
- **Unified plan buckets**: Quota/usage/entitlement logic is aligned around a single source of truth, including correct handling of “unlimited” enterprise plans.
- **Enterprise routing alignment**: Model selection and enterprise-specific flows behave consistently across pages and API routes.

### 🛡️ Admin Dashboard Deployment (IAP)
- **Windows-friendly deployment tooling**: PowerShell script + `.cmd` wrapper, with parity for bash/CI environments.
- **No-local-Docker option**: Support for Cloud Build based deployments for restricted machines.
- **Org-policy friendly ingress defaults**: Deployment defaults are aligned to common Cloud Run org policy constraints.

### 🧪 Universe Sandbox (Prototypes)
- **GitHub code-review workflow**: Prototype universe for reviewing diffs and generating structured delivery artifacts.
- **Document Intelligence**: A citation-aware doc indexing + Q&A pipeline designed for deterministic, auditable outputs.
- **Fail-closed deployment gating**: Deploy requests and approval checks are enforced before cloud deployment paths execute.

### 📚 Akashic: Document Intelligence Portal (Enterprise Prototype)
- **Document intelligence portal workflow**: Added an enterprise-ready “doc intel portal” flow designed for ingest → index → answer with citation-aware outputs.
- **Delivery operations templates**: Standardized a reusable set of deliverables (runbooks, verification, and customer-facing docs) to make delivery repeatable and auditable.
- **Distribution contracts & schemas**: Strengthened Universe distribution with explicit schemas and deterministic receipts/checksums to reduce drift across environments.

## 🚀 What's New in v5.3.1 (December 21, 2025)

### 🎛️ Control Plane (Evolve Orchestration)
- **Central orchestration**: Unified lifecycle control for Evolve executions, including consistent state transitions.
- **Failure recovery hooks**: Detection + recovery primitives to keep long-running workflows resilient.
- **Monitoring**: Real-time execution visibility with log aggregation.

### 🔐 Enterprise Infrastructure Hardening
- **Secret management expansion**: Safer credential handling across environments, with secure defaults and clear fallbacks.
- **Authentication middleware improvements**: Stronger validation and clearer operational errors.
- **Pricing & usage refinements**: Better plan alignment for entitlement and usage tracking.

### 🌐 Landing Page & Playground Go-Live
- **Production landing site**: Public-facing site and onboarding improvements.
- **Playground**: Interactive testing experience with enterprise-safe handling of configuration and credentials.

### 🧪 New Services & Building Blocks
- **Graph foundations**: Expanded graph context/storage primitives for future routing and diagnostics features.
- **Identity baseline**: Foundations for consistent user/session identity handling.

### 📊 Testing & Quality
- **Broader regression coverage**: Additional tests for enterprise flows and critical UI behavior.
- **Quality utilities**: Improvements to example validation and internal quality checks.
- **Docs updates**: Architecture and ecosystem documentation refreshed.

## 🚀 What's New in v5.3.0 (December 21, 2025)

### 🧬 Evolve v5: Commander Mode
- **status/approve/resume subcommands**: Monitor and control execution state as a “commander” for long-running workflows.
- **Human-in-the-Loop approvals**: Optional approval gates to keep higher-risk operations safe.
- **Policy-based execution**: Define execution policies via YAML for consistent governance.
- **Contract validation**: Validate contracts before and after runs to keep workflows deterministic and auditable.

### 🔍 Doctor Graph Enhancements
- **Evidence-based diagnostics**: Detect issues based on structured evidence rather than heuristics.
- **Multi-lens analysis**: Review systems from multiple perspectives to improve diagnosis quality.
- **Expanded subcommands**: More powerful diagnostics and report generation for advanced use cases.
- **Stronger repo comprehension**: Improved integration with codebase understanding graphs.

### ⌨️ Interactive CLI UX Improvements
- **Tab completion cycling**: Cycle candidates with repeated Tab presses (no dropdown dependency).
- **Input capture coordination**: Avoid conflicts with prompt libraries and interactive shells.
- **Stability fixes**: Addressed a “freezes on the second input” class of issues.

### 🏢 Enterprise Capabilities
- **OS Chat integration**: Cleaner separation between relay handling and helper functions.
- **Admin dashboard hardening**: Improved authentication and UI for secure operations.
- **Secret Manager integration**: Secure credential handling for enterprise deployments.

### 🧪 Test Coverage Expansion
- **Unit/E2E additions**: Expanded coverage for enterprise workflows and interrupt/resume behavior.
- **Type safety improvements**: Strengthened typed artifacts for traces, deltas, and gate reports.

### 📦 Internal Structure & Docs
- **Rules/templates separation**: Externalized Doctor rules/templates into configuration assets.
- **Schema additions**: Stronger contracts via shared schemas.
- **Documentation expansion**: Architecture docs updated to match the new execution and governance model.

## 🚀 What's New in v5.2.2 (December, 2025)

### Brand Refresh: MARIA OS
- **MARIA CODE → MARIA OS**: Repositioned the product as a “Self-Evolving Organizational Intelligence OS”, emphasizing human–AI collaboration as an operating system capability rather than a standalone tool.
- **Clearer product narrative**: Updated messaging to focus on long-term organizational value (roles, learning loops, and continuous evolution) over implementation details.
- **Docs & architecture alignment**: Refreshed core documentation and structure to match the MARIA OS direction and unify terminology across the repo.

## 🚀 What's New in v5.1.5 (December, 2025)

### Decision OS: Intuition Circuit & Fast Decision Path
- **Intuition Circuit**: Introduced a lightweight, pre-execution safety gate for high-impact operations, designed to keep workflows safe without slowing down day-to-day development.
- **Fast Decision Path**: Added a streamlined “fast lane” for repeat, pre-approved actions to reduce friction while preserving governance and auditability.

### Enterprise Policy & Governance Improvements
- **Role-aware decision policies**: Expanded Decision OS with enterprise-friendly, role-based policy evaluation so approvals/escalations align with organizational responsibilities.
- **Policy persistence & audit trail upgrades**: Strengthened policy storage and decision/audit records to make outcomes easier to trace and review at scale.

### A2A Messaging & Delivery Transport
- **Agent-to-agent messaging**: Added an asynchronous A2A messaging layer for coordinated multi-agent workflows, with stronger operational visibility and safer delivery semantics.
- **Multi-channel delivery**: Expanded delivery transport options so messages and outcomes can be routed through different delivery channels depending on the workflow needs.

### Platform Quality & Autonomy Upgrades
- **Operational best-practices packs**: Strengthened built-in operational guidance (including safer “single entrypoint” patterns and deterministic tool contracts) to improve reliability across environments.
- **Doctor quality auditing**: Expanded self-auditing capabilities to help validate quality across focus areas, scopes, and runtimes without requiring manual checklists.
- **Ecosystem/Universe management improvements**: Enhanced ecosystem configuration and lifecycle validation so governance and policy can be managed more consistently.

### Workflow Continuity & Decision Analytics
- **Sleep / resume workflows**: Added workflow pause/resume and locking primitives to support long-running work that must be safely suspended and resumed later.
- **Boundary regression analysis**: Introduced decision-boundary analytics to help tune boundary conditions using historical decision patterns without exposing sensitive internals.

### Response Quality & Help/Registry Improvements
- **Response quality gating**: Strengthened post-processing and quality gating to improve response consistency, robustness, and fallback behavior.
- **Help and registry refinements**: Improved command discovery and registry behavior to make advanced workflows easier to find and operate reliably.

### Auto-Dev, Setup & Execution UX
- **Auto-Dev guard integration**: Connected safety gating into Auto-Dev execution paths to better support Human-in-the-Loop workflows for higher-risk changes.
- **Config scaffolding improvements**: Expanded configuration scaffolding to simplify initializing and updating common project setups.

### Chat AI & Routing Refinements
- **Chat AI refactor**: Modularized the chat/response pipeline for better maintainability and more flexible context assembly.
- **Execution routing improvements**: Refined routing and quality gating to improve consistency across common interactive flows.

## 🚀 What's New in v5.0.2 (December, 2025)

### Structural AGI Platform & Self-Growth Architecture
- **Structural AGI Platform Release (v5.0.0)**: Formal release of the Structural AGI platform centered on a structural equilibrium engine and an enterprise OS doctor, providing a **Structure OS / Structural Equilibrium / Governance System** for organizations.
- **Structure Link & Org Doctor (v5.0.1)**: Enhanced link analysis and structural health checks on organization OS models, standardizing OS-level diagnostics for bottlenecks, loops, and flows via Org / Enterprise Doctor.
- **Self-Growth Architecture & Episode Memory System**: Introduced an **Episode Memory System** based on an episode memory schema and the `/ooda` command, unifying OODA cycles with TSA/Doctor reports to create a self-growth feedback loop.
- **TSA & Edge/OODA Systems**: Connected the `/tsa` hub command, Edge/TSA services, and OODA flow integration into a single Edge/OODA system from on-site symptoms (TSA) → OODA → Episode recording → Structure OS diagnosis.

### Brain Composition, CXO Agents & Knowledge Pack Ecosystem
- **Brain Composition Layer & CXO Agents**: Implemented a **brain composition layer & CXO agent system** using internal desire profiles, and integrated role-specific agents (Doctor / CXO / COO) into business decision commands.
- **Meta Super Pack & Knowledge Packs**: Expanded the **knowledge pack ecosystem** with a Meta Super Pack and multiple domain-specific Super Packs, providing a reusable knowledge base for structural diagnostics, executive decisions, and development support.
- **AI Agents Service & Business Commands**: Strengthened the AI Agents service and business slash commands such as `/sim`, enabling unified structural simulations, management scenario planning, and operations design.

### MLOps-Integrated Auto-Dev Engine (HITL-Ready)
- **Auto-Dev Core & Non-Breaking Policy**: Implemented an **autonomous development engine (Auto-Dev)** that combines structural risk checks with Enterprise OS orchestration to provide safe EXECUTE / SUGGEST_ONLY / ABORT_AND_ESCALATE modes.
- **MLOps Metrics & Feedback Loop**: Added an Auto-Dev metrics aggregator and auto-dev attempt logs to track **success rates, error classifications, and diff statistics**, making Auto-Dev outcomes visible from an MLOps perspective.
- **HITL (Human-in-the-Loop) Integration**: Connected Auto-Dev edit plans / patch metadata with Episode / Doctor / CXO reports, designing a HITL loop where **LLM suggestions, human review, and structural diagnosis** work together.
- **Quality Gate (Recommended)**: Copy the official template `config/templates/auto-dev.config.yaml` into your project as `./auto-dev.config.yaml` to enable deterministic post-run gates (typecheck/lint/test) with zero setup.

## 🚀 What's New in v4.4.9 (November, 2025)
### Functional enhancements
- **Improved image support**

## 🚀 What's New in v4.4.8 (October, 2025)
### Functional enhancements
- **Improved coding**
- **Enhanced video/image support**
- **Enhanced file support**

## 🚀 What's New in v4.3.46 (October, 2025)

### Functinal enhancements
- **Enhanced Natural Language Support**: Main commands called automatically by natural language input
- **Research and novel**: Research and novel generation now fully functional
- **Improved coding**

### 🎯 Interactive Improvements & Choice Memory
- **Choice Memory System**: Smart persistence of user selections across sessions
- **Enhanced Approval Prompts**: Improved interactive CLI experience with better formatting
- **Telemetry Enhancements**: Expanded tracking for better insights and performance monitoring
- **Jobs Command**: New media category command for job processing workflows
- **Express Server Updates**: Improved server architecture for better scalability

## Previous Release - v4.3.12 (September 16, 2025)

### ⚡ /code Orchestrator v2.1 (Fast · Safe · Deterministic)
- **Plan-first flow** with deterministic path/extension inference (TypeScript/React/Next/test runner/JS module type)
- **Output contract**: Single-line `OK:/WARN:/ERROR:` status and TTY one-line progress (`Writing n/m ...`)
- **Safe apply**: Atomic staging + full rollback on failure/SIGINT + partial-apply transparency
- **Interactive UX**: a/s/v/d/q shortcuts + 15s timeout (cancel default), resume via `.maria/memory/resume-plan.json`
- **Git integration**: Guard (CI default on), single-commit with branch/tag/push support
- **Cross-platform hardening**: Windows invalid chars, reserved names, path length validation
- **Security features**: Dotfiles protection, case-insensitive collision detection, simple secret detection

#### Key Flags
- Planning: `--plan-only`, `--sow`, `--dry-run`, `--output names|summary|detail`, `--preview-lines N`
- Apply: `--apply`, `--interactive`, `--yes`, `--max-files N`, `--root DIR`, `--rollback on|off`
- Git: `--git-commit on|off`, `--git-branch <name>`, `--git-tag <name|auto>`, `--git-push on|off`
- Safety: `--git-guard on|off`, `--allow-dotfiles`, `--confirm-overwrites <glob,glob>`

Examples:
```bash
# Plan-only mode (default) - shows what will be generated
maria /code --plan-only "create auth form + API"

# Apply with automatic approval
maria /code --apply --yes --max-files 5 "react component + tests"

# Interactive mode with detailed preview
maria /code --interactive --output detail --preview-lines 20 "routes + guards"

# Full Git workflow with commit, branch, tag, and push
maria /code --apply --yes --git-guard on --git-commit on \
      --git-branch feature/auth --git-tag auto --git-push on "implement auth + tests"
```

### 🎨 /image Generation (Imagen 4.0 Integration)
- **Multi-image generation**: Up to 8 images in parallel with rate limiting
- **Provider caps enforcement**: Size/format validation per model capabilities
- **Deterministic storage**: Hash-based deduplication with date hierarchy
- **Cost controls**: Client-side RPS slots + 429 backoff with exponential retry
- **Atomic persistence**: Stage + rename pattern with manifest tracking

#### Image Flags
- `--size WxH` (256-4096), `--format png|webp|jpg`, `--count 1..8`, `--model gemini-...`
- `--seed N` for determinism, `--out dir` for custom output location
- `--apply`, `--plan-only`, `--dry-run`, `--retry N`, `--budget PIXELS`

Examples:
```bash
# Generate single high-res image
maria /image "futuristic cityscape at sunset" --size 2048x2048 --apply

# Batch generation with seed for reproducibility
maria /image "abstract patterns" --count 4 --seed 42 --format webp --apply

# Plan-only mode to preview without generation
maria /image "concept art" --size 1024x1024 --plan-only
```

### 🎬 /video Generation (Veo 2.0 Integration)
- **Video generation**: Up to 60 seconds with configurable FPS and resolution
- **Mux pipeline**: Automatic MP4/WebM conversion when ffmpeg available
- **Frames fallback**: Graceful degradation to image sequence when muxing unavailable
- **Provider compatibility**: Unified error handling and retry logic
- **Session continuity**: Manifest references stored for resume capability

#### Video Flags
- `--duration S` (≤60), `--fps N` (≤caps), `--res WxH` (≤caps), `--format mp4|webm`
- `--model`, `--seed`, `--out`, `--apply`, `--plan-only`, `--dry-run`

Examples:
```bash
# Generate 10-second video
maria /video "ocean waves crashing" --duration 10 --fps 30 --apply

# High-res video with specific format
maria /video "time-lapse clouds" --res 1920x1080 --format webm --apply

# Plan-only to preview parameters
maria /video "animation test" --duration 8 --plan-only
```

### 🏗️ Build Status - All Systems Operational ✅
- **CLI NPM Package**: ESM + CJS builds successful (2.02MB/1.16MB)
- **VS Code Extension**: v3.8.0 with multi-modal AI capabilities
- **Landing Page**: Next.js production build (14/14 pages)
- **Auth Server**: TypeScript compilation success
- **Admin Dashboard**: IAP-protected build ready
- **Dynamic Version Sync**: Automated documentation updates

## 🚀 Previous Updates in v4.2.0 (September 2, 2025)

### ✨ Major Achievements
- **100% READY Status**: All 74 commands fully operational (Week 2 Enterprise Systems)
- **Zero Build Errors**: All projects compile without errors or warnings
- **UIR System**: Universal Intelligence Router with enterprise governance
- **Real-time Dashboard**: Live usage monitoring with WebSocket integration
- **Firebase Functions**: Serverless backend with auto-scaling
- **Enhanced Telemetry**: BigQuery analytics with Firestore sync
**Complete removal of all V2 references** - Fully removed 180+ V2 naming conventions, achieving a unified naming scheme. All commands, including SlashCommand, RecallCommand, and RememberCommand, have migrated to the standard naming.

## 🔐 Admin Dashboard with IAP (2025-09-01)
**Enterprise admin dashboard** - Implemented full protection via Google Cloud Identity-Aware Proxy (IAP). Provides a secure admin interface with OAuth2.0 authentication, @bonginkan.ai domain restriction, and role-based access control.

🌐 **Homepage**: [https://maria-code.ai/](https://maria-code.ai/)
🛡️ **Admin Dashboard**: [https://admin.maria-code.ai/](https://admin.maria-code.ai/) (IAP Protected)

[![TypeScript](https://img.shields.io/badge/TypeScript-5.0%2B-blue)](https://www.typescriptlang.org/)
[![Node.js](https://img.shields.io/badge/Node.js-20%2B-green)](https://nodejs.org/)
[![npm](https://img.shields.io/npm/v/@bonginkan/maria)](https://www.npmjs.com/package/@bonginkan/maria)
[![Quality Achievement](https://img.shields.io/badge/Quality-Historic%20Zero%20Errors-gold)](https://github.com/bonginkan/maria)
[![TypeScript Errors](https://img.shields.io/badge/TypeScript%20Errors-0-brightgreen)](https://github.com/bonginkan/maria)
[![ESLint Errors](https://img.shields.io/badge/ESLint%20Errors-0-brightgreen)](https://github.com/bonginkan/maria)
[![Authentication](https://img.shields.io/badge/Auth-OAuth2%2BPKCE-blue)](https://github.com/bonginkan/maria)
[![Security](https://img.shields.io/badge/Security-Quantum%20Resistant-purple)](https://github.com/bonginkan/maria)
[![Enterprise Ready](https://img.shields.io/badge/Enterprise-Fortune%20500%20Ready-gold)](https://github.com/bonginkan/maria)

## ⚡ QUICK.START

### 👤 For Users: CLI Installation (Recommended)
```bash
$ npm install -g @bonginkan/maria
```

Notes:
- You can also run the CLI without installing globally via: `npx @bonginkan/maria --help`

### 💡 DeepenAndPropose (DAP) (optional post-chat suggestions; default ON)
- **Default**: DAP is **ON** (adds a suggestions block at the end of chat responses for all users)
- **Disable (Chat)**: `MARIA_ENABLE_CHAT_DAP=0`
- **Disable (CLI)**: `MARIA_ENABLE_CLI_DAP=0`
- **CLI JSON safety**: DAP is **never appended** for `--json` / `output=json_only` machine outputs

### 🪟 For Users (Windows): Add npm global prefix to PATH
On Windows, npm's global bin directory may not be on PATH by default. After installing, verify and add the directory returned by `npm prefix -g` to PATH.

```powershell
# Show npm global prefix (this directory should be on PATH)
npm prefix -g;

# Temporarily add to current PowerShell session
$env:Path += ";" + (npm prefix -g).Trim(); Get-Command maria;

# Persist for the current user (idempotent)
$npmBin = (npm prefix -g).Trim();
$userPath = [Environment]::GetEnvironmentVariable('Path','User');
if ($userPath -notlike "*$npmBin*") {
  [Environment]::SetEnvironmentVariable('Path', ($userPath.TrimEnd(';') + ";" + $npmBin), 'User');
  "Added to PATH: $npmBin";
} else {
  "Already on PATH: $npmBin";
}

# Restart PowerShell, then verify
maria --version;
```

Notes:
- Default location is typically `%APPDATA%\npm` on Windows.

### 🧑‍💻 For Contributors: Local development (pnpm) / Build & Manifest
```bash
# Quiet, stale-aware manifest + build + verify
pnpm build

# Force READY manifest for demos (all commands READY)
pnpm ensure:manifest:all

# Full regeneration (verbose manifest generation)
pnpm generate:manifest

# See detailed build logs
VERBOSE=true pnpm build
```

Notes:
- Build runs a quiet/stale-aware manifest step first, then bundles via tsup.
- The READY manifest is automatically copied to `dist/` by the build.
- CI npm auth: use `.npmrc.ci` with `NPM_TOKEN` (local `.npmrc` doesn’t require it).

## Blogs (LP) × Firestore publish (Ops SSOT)

- **Runbook (SSOT)**: `docs/06-operations/blogs-firestore-runbook.md`
- **Daily flow (recommended)**: generate (3/day) → sync → auto-publish

```bash
pnpm -s build
node dist/cli.cjs /blog generate --apply --force --replace
FIRESTORE_PROJECT_ID=maria-code-470602 node dist/cli.cjs /blog sync --in blogs --apply --publish
```

### Sync specific posts (copy/paste)

```bash
# Publish slot 1 for a specific day
pnpm -s build
FIRESTORE_PROJECT_ID=maria-code-470602 node dist/cli.cjs /blog sync --in blogs --date 20260106 --slot 1 --apply --publish

# Draft-only sync (no auto-publish)
FIRESTORE_PROJECT_ID=maria-code-470602 node dist/cli.cjs /blog sync --in blogs --date 20260106 --slot 3 --apply
```

## Daily Self-Evolve (Universe, Ops SSOT)

- **Runbook (SSOT)**: `docs/06-operations/universe-daily-self-evolve.runbook.v2.md`
- **Schemas (SSOT)**:
  - `docs/schemas/universe-daily-self-evolve.daily-plan.v2.schema.json`
  - `docs/schemas/universe-daily-self-evolve.qe-report.schema.json`

```bash
# Daily self-evolution workflow (v2.1)
maria run daily --date 20260106 --focus-path src --auto-apply execution
maria run show <runId> --items
```

### Daily automation (cron)

Run:

```bash
FIRESTORE_PROJECT_ID=maria-code-470602 ./scripts/blogs/cron-daily-blogs.sh
```

### 🔗 VS Code Extension (NEW)
**AI-powered coding directly in your editor**

1. **Install Extension**: Search "MARIA CODE Assistant" in VS Code Extensions
2. **Install CLI** (for full features):
   ```bash
   npm install -g @bonginkan/maria
   ```
3. **Authenticate**: `Cmd/Ctrl + Shift + P` → "MARIA: Login to MARIA"

#### VS Code Features (v3.8.0):
- **🤖 Natural Language Coding**: `Cmd/Ctrl + Alt + M` - Generate production-ready code
- **🎨 AI Image Generation**: `Cmd/Ctrl + Alt + I` - Imagen 4.0, up to 1792x1024 resolution
- **🎬 AI Video Creation**: `Cmd/Ctrl + Alt + V` - Veo 2.0, videos up to 60 seconds
- **🔄 Smart Dual Mode**: Automatic CLI detection + REST API fallback
- **🔒 Enterprise Security**: JWT authentication, PII protection, rate limiting
- **📊 Activity Panel**: Quick actions, generation history, account status
- **⚡ Performance**: <500ms activation with dynamic imports

**Marketplace**: [MARIA CODE Assistant](https://marketplace.visualstudio.com/items?itemName=bonginkan.maria-code-assistant)

### Start MARIA CLI
```bash
$ maria
```

### Check Version
```bash
$ maria --version
```

## 🌐 Macnica LLM Integration (VPN)

MARIA can connect to **Macnica LLM Trial** servers via VPN for enterprise AI inference.

### Quick Setup (VPN Required)

```bash
# 1. Verify VPN connection
ping -c 3 10.0.1.108

# 2. Configure MARIA for Macnica LLM
export VLLM_API_BASE="http://10.0.1.108:7000/v1"
export DEFAULT_PROVIDER="vllm"

# 3. Test connection
maria "Hello from Macnica LLM"
```

### Features
- **OpenAI-Compatible API**: Uses existing vLLM provider
- **No Code Changes**: Simple environment variable configuration
- **Seamless Integration**: Works with all MARIA commands (`/code`, `/help`, etc.)
- **Automatic Fallback**: Returns to default provider when VPN disconnects

### Documentation
- **Setup Guide**: [macnica/MARIA_USAGE_GUIDE.md](./macnica/MARIA_USAGE_GUIDE.md)
- **VPN Setup**: [macnica/VPN setup guide (PDF)](./macnica/VPN%E6%8E%A5%E7%B6%9A%E6%89%8B%E9%A0%86.pdf)
- **Troubleshooting**: [macnica/troubleshooting.md](./macnica/troubleshooting.md)

### Connection Details
- **API Endpoint**: `http://10.0.1.108:7000/v1`
- **VPN Timeout**: 8 hours (30 min idle disconnect)
- **Supported Models**: Check with `curl http://10.0.1.108:7000/v1/models`

For detailed instructions, see [Macnica MARIA Usage Guide](./macnica/MARIA_USAGE_GUIDE.md).

## 🏗️ MARIA OS Foundation Quality Standards

**Implementation based on Foundation quality spec v1.0**

Quality standards and development guidance for building MARIA OS Foundation as a durable, non-fragile system.

### Required checks

When implementing/changing foundation components (Parent MARIA, Task/Envelope, Evidence/Decision Log, Risk Gate, Sandbox/Isolation, Tool Registry, Observability/Cost), confirm the following:

- **Explicit ownership**: Include `requesterId`, `decisionOwner`, `approvalOwner` (required for high+) in TaskSpec
- **State transitions**: Re-runs must generate a new taskId; `done → planned` is forbidden
- **RiskTier critical**: No automatic execution; even with approval, no immediate execution; no exceptions
- **EvidenceMap format**: `evidenceId`, `type`, `ref`, `relevance` are required (at least one item)
- **Audit logs**: Correlation ID required; automatic masking of sensitive information
- **Acceptance tests**: Must satisfy S1–S5 scenarios

### ADR requirement detection

Automate ADR requirement detection based on PR labels and file paths:

```bash
# Check locally
pnpm tsx scripts/check-adr-requirement.ts --files "src/policy/foo.ts" --labels "area:authz"

# Auto-run in GitHub Actions (on PR creation)
```

**ADR is required when**:
- PR labels include: `area:authz`, `area:governance`, `area:schema`, `area:sandbox`, `area:evidence`, `area:tools`, `area:observability`, `area:finops`
- File paths include: `/policy/`, `/authz/`, `/schemas/taskSpec/`, `/schemas/envelope/`, `/sandbox/`, `/evidence/`, `/registry/`, `/finops/`, `/maria-os-foundation/`
- Breaking changes: schema major bump, state machine changes, approval condition changes

### References

- **Quality spec**: `docs/09-maria-os-qe/qe-test.txt`
- **Required artifacts**: `docs/09-maria-os-qe/required-artifacts.md`
- **Knowledge pack**: `config/knowledge-packs/maria-os-foundation-quality-pack.yaml`
- **Implementation**: `src/services/maria-os-foundation/`
- **ADR requirement guide**: `docs/09-maria-os-qe/adr-requirement-guide.md`

### PR Definition of Done

For foundation-related PRs, review the required artifacts checklist in `docs/09-maria-os-qe/required-artifacts.md`.

## 🔧 ADVANCED.OPERATIONS

### Update to Latest
```bash
$ npm update -g @bonginkan/maria
```

### Force Reinstall
```bash
$ npm install -g @bonginkan/maria --force
```

### Uninstall
```bash
$ npm uninstall -g @bonginkan/maria
```

## 💡 First Commands After Installation

```bash
# Show all available commands
> /help

# Secure OAuth2.0 + PKCE authentication
> /login

# Natural language code generation
> /code create a React app

# Git Intelligence Layer (NEW)
> /git wire                    # Initialize Git Intelligence Layer
> /git index update --since 14d  # Update commit index
> /git intent now --llm on      # Infer developer intent
> /git theme recent --llm on    # Extract development themes
> /git route auto              # Auto-route to Doctor/Coder

# Generate images with AI
> /image A sunset scene

# Create videos with AI
> /video A cat playing

# Generate voice with AI
> /voice Tell me a story
```

**🤖 8 AI Providers Supported**: OpenAI (GPT-4o, o1), Anthropic (Claude), Google (Gemini), xAI (Grok), Groq, plus **Local LLM support** via Ollama, LM Studio, and vLLM for complete privacy and offline usage.

**Transform coding from syntax to intent** - Simply articulate your requirements in natural language and witness MARIA intelligently generate, refine, and optimize your code with enterprise-grade precision and **guaranteed zero errors**.

### 🏥 Doctor Core Diagnostics (v2.0)
Fast, safe, deterministic diagnostics with one-line status, JSON output, and optional low‑risk fixes.

```bash
# Fast diagnostics (p95 < 800ms)
/doctor --core

# JSON output (contract schema v1)
/doctor --core --json

# Preview low-risk fixes (dry-run by default)
/doctor --core --fix

# Apply low-risk file fixes (TTY only)
/doctor --core --fix --dry-run=false --risk-level 0.2 --yes --allow-json-merge
```

Notes:
- Non-interactive/CI/safe mode forces preview-only and skips network checks.
- `--allow-json-merge` enables safe shallow JSON merges (e.g., `package.json` scripts).
- One-line status uses `OK:/WARN:/ERROR:`; secrets are redacted in all outputs.

### ✅ Quality SSOT (lint:truth / MARIA OS Foundation quality / CI Loop)

#### 🎯 MARIA OS required quality gates

**As the MARIA OS baseline standard, all new code creation, modifications, repairs, and periodic maintenance MUST pass the following quality gates:**

1. **lint:truth** - repo-wide lint check (SSOT)
   ```bash
   pnpm lint:truth
   ```

2. **pnpm exec tsc --noEmit** - TypeScript typecheck (no emit)
   ```bash
   pnpm exec tsc --noEmit
   ```

Code that fails these checks cannot be merged into any component, including MARIA OS Foundation, doctor, code, develop, and auto-dev.

The quality gate is implemented in `src/services/maria-os-foundation/quality/MariaOsQualityGate.ts` and is automatically enforced when commands run.

#### 🧪 E2E Testing Configuration Best Practices (NEW)

**Foundational best practices for E2E test configuration in MARIA OS**

When adding/updating E2E tests, follow these best practices:

- **Vitest config**: use `pool: 'forks'` and set `resolve.alias` to the correct Vitest package path
- **Mock server**: use dynamic port allocation (`server.listen(0, ...)`) and ensure cleanup via `try/finally`
- **Environment variables**: fix `CI=true`, `NODE_ENV=test`, `MARIA_TEST_MODE=1`, etc.

**Reference docs**:
- `docs/BEST_PRACTICE/E2E_TESTING_CONFIGURATION_BEST_PRACTICE.md` - Vitest config & mock-server patterns
- `docs/BEST_PRACTICE/E2E_TESTING_SMOKE_LIGHT_BEST_PRACTICE.md` - Smoke/Light/Full suite operations
- `config/knowledge-packs/e2e-testing-configuration-pack.yaml` - knowledge pack

**Implementation example**: `tests/e2e/slash-commands/akashic.ask.llm.spec.ts`

#### Quality SSOT details

- **lint SSOT**: The lint source of truth for this repo is **`pnpm lint:truth`** (whole repo: `src/`, `scripts/`, `tests/`, `tools/`)
  - **JSON**: `pnpm lint:truth:json`
  - **Shortcut**: `pnpm lint:repo` (= `pnpm lint:truth`)
  - **Helper (fast)**: `pnpm lint:truth:src` (src only; not SSOT)
- **Doctor**: runs SSOT `lint:truth`, classifies results, preserves evidence (artifacts), and optionally connects to safe fixes.
- **MARIA OS Foundation quality standard**: when changing `src/services/maria-os-foundation/`, follow S1–S5 acceptance scenarios and required artifacts such as EvidenceMap/DecisionLog (see `docs/09-maria-os-qe/*`).
- **CI Loop (self-maintaining)**: iterates SSOT gates (lint/typecheck/tests...) per `docs/quality/ci-loop/ci-loop.operational-spec.md` to continuously self-maintain quality.

#### pnpm commands by purpose (recommended entrypoints)

The SSOT list of all scripts is **`package.json` → `scripts`** (list via `pnpm -s run`).

```bash
# Install / Dev
pnpm install
pnpm dev

# Build / Manifest
pnpm build
pnpm ensure:manifest
pnpm verify:manifest
pnpm generate:manifest

# Lint (SSOT)
pnpm lint:truth
pnpm lint:truth:json
pnpm lint:repo          # short alias (= lint:truth)
pnpm lint:truth:src     # fast helper (src only)

# Typecheck
pnpm type-check:syntax
pnpm exec tsc --noEmit  # MARIA OS quality gate typecheck (SSOT)
#
# Optional (non-SSOT / deeper checks)
pnpm type-check:full

# Tests
pnpm test
pnpm test:integration
pnpm test:e2e
pnpm test:coverage

# Quality gates (PR/CI)
pnpm quality-gate
pnpm quality-gate:ci

# CI Loop / Doctor (ops entrypoints)
pnpm loop            # run lint/typecheck/unit under the same runId and aggregate evidence under artifacts (e2e/golden are thinned by default)
pnpm loop:analysis   # loop + best-effort LLM analysis (continues even on analysis failure; persists analysisStatus)
pnpm loop:full       # one-shot run equivalent to CI (includes e2e/golden)
pnpm maria:doctor    # avoid conflict with pnpm built-in `pnpm doctor`; use maria:doctor instead
pnpm doctor:core     # existing Doctor Core suite (= pnpm test:doctor-core)

# Doctor (background ops)
pnpm -s maria:doctor:bg
pnpm -s maria:doctor:status -- --run-id <runId>
pnpm -s maria:doctor:wait -- --run-id <runId>
```

#### CLI (all commands) background execution / job management

Long-running jobs (e.g., `doctor`, `auto-dev`, `/universe ...`) can return immediately with `--background`.

```bash
# Example: run doctor in the background (returns immediately and prints runId + next commands)
maria doctor --background

# Job list (recent runIds)
maria jobs list

# Status / wait / logs
maria jobs status <runId>
maria jobs wait <runId>
maria jobs logs <runId> --tail 200
maria jobs logs <runId> --stderr --tail 200
```

Artifacts/logs are saved under `artifacts/maria/jobs/<runId>/` (`status.json` / `logs/stdout.log` / `logs/stderr.log`).

## 🔁 Resume Previous Work

Continue where you left off using the workflow resume command:

```bash
maria /workflow/resume --latest
# or resume a specific task with helpful flags
maria /workflow/resume <taskId> --tests --fix
```

See design details in `docs/RESUME_FUNCTION_DESIGN.md`.

## 🧪 Testing & CI

Core commands (lightweight default; heavy suites are explicit):

```bash
# Discover + run lightweight tests (unit/default)
pnpm test

# Watch mode for fast TDD (default suite)
pnpm test:watch

# Verbose listing via run (shows files executed)
pnpm test:list

# Dedicated suites (explicit configs; for IDE debugging, specify `--config`)
pnpm test:integration
pnpm test:security
pnpm test:contract
pnpm test:e2e

# Run all non-E2E suites sequentially
pnpm test:all
```

Coverage and JUnit (CI-friendly):

```bash
# Enable coverage + junit reporters during CI (LCOV merged)
pnpm test:ci

# Manually enable coverage on default suite
pnpm test:coverage

# Merge per-suite LCOV into coverage/lcov.info
pnpm coverage:merge
```

Notes:
- Default suite includes `src/**/__tests__/**` and `tests/**`, but excludes heavy suites and `**/*.slow.*`, `**/*.flaky.*`, `**/__fixtures__/**`.
- Heavy suites (integration/security/contract/e2e) always run with `--config` for stable discovery.
- CI emits coverage per suite under `reports/coverage/{unit,integration,security,contract}` and merges LCOV → `reports/coverage/lcov.info`.
- JUnit XML emits by suite under `reports/junit/*.xml` when CI.
- For debugging individual suites in an IDE, specify `--config vitest.<suite>.config.ts`.

Benches:

```bash
pnpm bench:42:rbac   # security RBAC bench (JSON artifact preserved)
pnpm bench:43:ai     # AI orchestration bench
pnpm bench:44:dx     # Developer experience/command intelligence bench
```


## 🧪 Local LLM Testing & Self-Evolution

### 🚀 Comprehensive Testing with Local LLMs (NEW)
**Production-grade testing without API costs** - Apple Siliconではまず **Ollama常用**が安定です（LM Studioは壊れやすい場合があります）。

```bash
brew install ollama
open -a Ollama
ollama pull qwen2.5:14b-instruct

export LOCAL_MODE=1
export MARIA_AUTH_MODE=local
export MARIA_LOCAL_LLM_PROVIDER=ollama
export MARIA_LOCAL_LLM_MODEL=qwen2.5:14b-instruct
export OLLAMA_API_BASE=http://localhost:11434
export LMSTUDIO_BASE_URL=http://127.0.0.1:1234/v1
export MARIA_LOCAL_LLM_MODEL_FAST_LMSTUDIO=openai/gpt-oss-20b
export MARIA_LOCAL_LLM_MODEL_HEAVY_LMSTUDIO=openai/gpt-oss-120b
export MARIA_LOCAL_LLM_MODEL_LMSTUDIO=qwen3-30b-a3b-thinking-2507-mlx

cd /Users/bongin_max/maria_code || exit 1
ollama list | head -n 20
curl -s http://127.0.0.1:1234/v1/models | jq -r '.data[].id' | egrep 'openai/gpt-oss-(120b|20b)|qwen3-30b-a3b-thinking-2507-mlx' || true
echo '/ceo --provider lmstudio --model openai/gpt-oss-20b "日本語で、3行で自己紹介して"' | maria
echo '/ceo --provider lmstudio --model openai/gpt-oss-120b "日本語で、短い意思決定メモを作って: 目的/選択肢/推奨案"' | maria
echo '/ceo --provider lmstudio --model qwen3-30b-a3b-thinking-2507-mlx "日本語で、問題を分解してから結論を1つ出して"' | maria
```

**📊 Verified Results**: 55.6% test pass rate with Local LLM, 100% success on code generation tasks.

- SSOT doc: `docs/01-setup/local-mode-local-llm-ssot.md`
- Testing guide: `docs/BEST_PRACTICE/TESTING_BY_LOCAL_LLM.md`
- Template: `config/templates/local-llm.env.example` (copy/paste into `.env.local`)

### LM Studio (optional)
LM Studioを使う場合は `.env.local` で以下を指定してください（APIサーバ起動とモデルロードが必要です）。

```bash
export MARIA_LOCAL_LLM_PROVIDER=lmstudio
export MARIA_LOCAL_LLM_MODEL=openai/gpt-oss-20b
export LMSTUDIO_BASE_URL=http://127.0.0.1:1234/v1
export MARIA_LMSTUDIO_AUTO_START=1
```

### 🔄 Self-Evolution with /evolve Command
**Autonomous improvement system** - MARIA can evolve itself using Local LLMs:

```bash
# Trigger self-evolution
$ maria /evolve --target "improve code generation"

# Monitor evolution progress
$ maria /evolve --status

# Review evolution proposals
$ maria /evolve --review
```

## 🎉 NEW: VS Code Extension for MARIA CODE v3.8.0

### 🚀 Complete VS Code Integration (Achieved August 31, 2025)
**Production-Ready VS Code Extension with Full AI Capabilities**

#### ✨ Key Features of the VS Code Extension
- **🤖 Natural Language Code Generation**: Generate, modify, and fix code with AI
- **🎨 AI Image Generation**: Create images directly in VS Code (Imagen 4.0)
- **🎬 AI Video Generation**: Generate videos up to 60 seconds (Veo 2.0)
- **🔄 Dual Execution Modes**: Seamless CLI/REST API fallback
- **🔐 Enterprise Security**: JWT authentication with rate limiting
- **📊 Analytics & Telemetry**: Privacy-respecting usage tracking

#### 📦 Installation Options
```bash
# Method 1: VS Code Marketplace (Coming Soon)
# Search for "MARIA CODE Assistant" in VS Code Extensions

# Method 2: Manual Installation
# Download .vsix from releases and install via:
# CMD/CTRL + SHIFT + P → "Extensions: Install from VSIX"
```

#### ⌨️ VS Code Keyboard Shortcuts
- `Ctrl/Cmd + Alt + M` - Generate Code
- `Ctrl/Cmd + Alt + I` - Generate Image
- `Ctrl/Cmd + Alt + V` - Generate Video

#### 🏗️ Complete 4-Week Implementation
- **Week 1-2**: Core extension with CLI integration ✅
- **Week 3**: REST API fallback system ✅
- **Week 4**: Marketplace publishing & production deployment ✅

**[Detailed Setup Guide](#vs-code-extension-setup-guide)**

## ⭐ **NEW: v4.1.4 Revolutionary Features**

### 🎯 **73 Production-Ready Commands** (68% READY Status)
**Comprehensive Command Ecosystem with Dynamic Health System**

```bash
# Core command categories with READY status
/help                          # Smart command discovery system
/code create a full-stack app  # AST-powered code generation 
/memory remember key insights  # Dual memory architecture
/graphrag search codebase      # Knowledge graph queries
/multilingual translate code   # Multi-language support
/research analyze trends       # AI-powered research tools
/ai gpu status                 # Hardware optimization
```

#### **Command Health Monitoring**
- **Total Commands**: 73 registered commands
- **READY Commands**: 50 fully functional (68.5% success rate) 
- **PARTIAL Commands**: 5 with limited functionality
- **BROKEN Commands**: 18 under development/maintenance
- **Dynamic Discovery**: Only READY commands shown in `/help`

### 🧠 **Advanced Memory Systems** (NEW)
**Dual-Architecture Cognitive Memory Engine**

```bash
# Memory system commands
/memory remember "React best practices for hooks"
/memory recall "authentication patterns" 
/memory status                 # View memory utilization
/memory forget "outdated info" # Selective memory cleanup

# Graph RAG integration
/graphrag search "error handling patterns"
/graphrag index codebase       # Build knowledge graphs
```

#### **Memory Architecture Features**
- **System 1 Memory**: Fast, intuitive knowledge retrieval
- **System 2 Memory**: Deep reasoning and analysis traces
- **Knowledge Graphs**: AST-based semantic relationships
- **Vector Search**: Hybrid embeddings for context matching
- **Delta Detection**: Git-integrated change tracking

### 🌍 **Multilingual Development Support** (NEW)
**Natural Language Programming in Multiple Languages**

```bash
# Multilingual code generation
/multilingual translate --from=python --to=typescript
/language set japanese         # Set interface language
/code create a React component (example of Japanese prompt) # Japanese natural language
/code créer une API REST       # French natural language
```

#### **Language Support**
- **Programming Languages**: TypeScript, Python, JavaScript, Go, Rust, Java
- **Natural Languages**: English, Japanese, Chinese, Korean, Spanish, French
- **Code Translation**: Cross-language code conversion
- **Locale Support**: Region-specific development patterns

###