@leejungkiin/awkit 1.7.1 → 1.7.5

package/docs/history/PRD.v2.md

@@ -0,0 +1,57 @@
+# Product Requirement Document (PRD) - GreetingApp
+
+## Revision History
+| Version | Date | Description | Author |
+|---|---|---|---|
+| v1.0 | 2026-06-22 | Initial PRD for GreetingApp | Antigravity Orchestrator |
+
+---
+
+## 1. Executive Summary
+GreetingApp is a micro-application designed to deliver personalized, localized, and dynamic greetings to users. It adapts to the user's name, current time of day, and language preferences.
+
+## 2. Objectives & Goals
+- Provide dynamic greetings based on user local time (Morning, Afternoon, Evening, Night).
+- Support multi-language greetings (English, Vietnamese, Japanese).
+- Track user greeting history and statistics.
+- Expose both CLI and REST API interfaces.
+
+## 3. User Personas & Use Cases
+- **End User:** Wants to see a welcoming, contextual message when logging in or using the CLI.
+- **Developer:** Wants an easy-to-integrate greeting microservice API for downstream services.
+
+## 4. Functional Requirements
+1. **Dynamic Greeting Generation:**
+   - Detects local time of user.
+   - Personalizes with name (fallback to "Guest").
+2. **Localization (i18n):**
+   - Supports: English (`en`), Vietnamese (`vi`), Japanese (`ja`).
+3. **Greeting Analytics / History:**
+   - Stores logs of generated greetings (User, Timestamp, Language).
+   - Exposes statistics (e.g., total greetings generated, most active user).
+4. **Interfaces:**
+   - Command Line Interface (CLI): `awkit greet --name=Alice`
+   - REST API endpoint: `GET /api/greet?name=Alice&lang=vi`
+
+## 5. Non-Functional Requirements
+- **Performance:** Response time for greeting generation under 50ms.
+- **Reliability:** Storage fallback to memory if database/file storage is offline.
+- **Extensibility:** Easy configuration to add new languages.
+
+## 6. System Flow & Sequence Diagram
+```mermaid
+sequenceDiagram
+    autonumber
+    actor User
+    participant Client as CLI / API Client
+    participant Engine as Greeting Engine
+    participant DB as Storage / History DB
+
+    User->>Client: Triggers greeting command/request (name, lang)
+    Client->>Engine: Resolve greeting configuration
+    Engine->>Engine: Validate input & detect Time of Day
+    Engine->>DB: Log transaction (user, time, format)
+    DB-->>Engine: Log confirmation
+    Engine->>Client: Return formatted greeting string
+    Client->>User: Display greeting output
+```

package/docs/history/brainstorm_antigravity_unified_architecture.v1.md

@@ -0,0 +1,105 @@
+# Brainstorm: Tích hợp Kiến trúc Đa Tác tử và Triết lý Wise Teacher vào Antigravity (AWKit)
+
+## Lịch sử Hiệu chỉnh (Revision History)
+
+| Phiên bản | Ngày | Người thực hiện | Nội dung thay đổi |
+| :--- | :--- | :--- | :--- |
+| v1.0 | 2026-06-14 | Antigravity Orchestrator | Khởi tạo tài liệu gộp thống nhất cả 3 nghiên cứu: Wise Teacher, Fable 5 Multi-Agent và Antigravity Subagents. |
+
+---
+
+## Tóm tắt Điều hành (Executive Summary)
+
+Tài liệu này đề xuất phương án tối ưu hóa toàn diện Antigravity (AWKit) bằng cách kết hợp:
+1. **Triết lý giảng dạy cuốn chiếu (Wise Teacher):** Đảm bảo user nắm vững Vấn đề (Problem), Giải pháp (Solution), và Bối cảnh (Broader Context).
+2. **Kiến trúc đa tác tử phân lớp (Manager-Workers-Critic-Safety Router):** Chống "Context Rot" và tối ưu hóa hiệu năng theo mô hình của Fable 5.
+3. **Cơ chế Subagents của Antigravity:** Tận dụng tối đa built-in `research` và các custom sub-agents để thực thi an toàn, cô lập ngữ cảnh và nâng cao hiệu quả làm việc.
+
+---
+
+## 1. Triết lý Giảng dạy Cuốn chiếu (Wise Teacher Protocol)
+
+Phương pháp này chuyển đổi hoạt động của Antigravity từ "chỉ bàn giao code" sang "chuyển giao tri thức sâu sắc" cho con người một cách cuốn chiếu (Incremental Learning).
+
+```mermaid
+graph TD
+    A[Bắt đầu Mục tiêu] --> B[User tự trình bày hiểu biết - Restatement]
+    B --> C[AI phân tích & lấp đầy lỗ hổng kiến thức]
+    C --> D[Quiz kiểm tra bằng AskUserQuestion]
+    D -->|Sai/Chưa hiểu sâu| C
+    D -->|Đã Master| E[Đánh dấu hoàn thành mục trong checklist]
+```
+
+### 3 Trụ cột Kiến thức Bắt buộc:
+- **The Problem (Vấn đề):** Tại sao vấn đề tồn tại, các nhánh hướng đi để giải quyết.
+- **The Solution (Giải pháp):** Tại sao chọn phương án này, quyết định thiết kế và edge cases.
+- **Broader Context (Bối cảnh rộng):** Tác động lâu dài của thay đổi đối với toàn bộ hệ thống.
+
+### Cơ chế Tương tác:
+- **Proactive Restatement:** Buộc user tự tóm tắt trước để AI dò tìm lỗ hổng kiến thức thực tế.
+- **Adaptive Explanations (ELI5 / ELI14 / ELII):** Giải thích linh hoạt từ mức cực kỳ đơn giản (cho khái niệm trừu tượng) tới mức chuyên sâu (cho logic mã nguồn chi tiết).
+- **Interactive Quizzing:** Sử dụng tool `AskUserQuestion` để tạo các câu đố trắc nghiệm (đảo lộn đáp án, ẩn kết quả cho tới khi nộp bài).
+
+---
+
+## 2. Kiến trúc Điều phối Đa Tác tử (Multi-Agent Control Plane)
+
+Dựa trên nghiên cứu về Fable 5 và các tài liệu chính thức từ OpenAI/Google, chúng ta cần tránh việc dồn mọi log thô vào một luồng chat duy nhất (gây ra **Context Rot**). Thay vào đó, thiết lập một Control Plane phân lớp:
+
+```mermaid
+graph TD
+    Manager[Manager / Synthesizer] -->|1. Phân loại & Định tuyến| Router[Safety Router / Classifier]
+    Manager -->|2. Phân rã nhiệm vụ| Workers[Bounded Specialists / Workers]
+    Workers -->|3. Trả kết quả tóm tắt| Critic[Critic / Verifier Pass]
+    Critic -->|4. Phản biện & Đối chiếu| Manager
+    Manager -->|5. Cập nhật| Ledger[External Work Ledger]
+```
+
+### Các Thành phần Cốt lõi:
+1. **Manager (Trình điều phối):** Giữ bối cảnh điều hành chính, phân rã công việc và tổng hợp kết quả cuối cùng.
+2. **Workers (Tác tử chuyên biệt):** Chỉ thực hiện các tác vụ đọc-ghi trong ranh giới được chỉ định, chỉ trả về **Structured Summary JSON** thay vì log thô.
+3. **Critic / Verifier:** So chéo kết quả, phát hiện mâu thuẫn, ngăn ngừa việc AI "chốt quá sớm" vào các giả thuyết sai (early commitment).
+4. **Safety Router:** Nhận diện các tác vụ nguy cơ cao (cyber, database write) để định tuyến sang degraded mode hoặc kích hoạt cổng phê duyệt (Approval Gate).
+5. **External Work Ledger:** Sổ ghi chép trạng thái ngoài model (lưu tại `.brain/session.json`) giúp khôi phục ngữ cảnh (resumable state) trên mọi họ mô hình (Claude, GPT, Gemini).
+
+---
+
+## 3. Hiện thực hóa bằng Cơ chế Subagents của Antigravity
+
+Chúng ta ứng dụng trực tiếp tài liệu hướng dẫn của Google Antigravity 2.0 để cấu trúc các vai trò trên:
+
+```mermaid
+sequenceDiagram
+    autonumber
+    actor User
+    participant Manager as Manager (Orchestrator)
+    participant Research as Research Agent (Built-in)
+    participant Critic as Critic Agent (Custom)
+
+    User->>Manager: Yêu cầu task COMPLEX
+    Manager->>Research: invoke_subagent (Quét codebase cô lập)
+    Research-->>Manager: Trả về Structured Summary JSON (Idle)
+    Note over Manager: Xây dựng giải pháp
+    Manager->>Critic: invoke_subagent (Yêu cầu review chéo)
+    Critic-->>Manager: Trả về Báo cáo lỗi tiềm ẩn & phản biện (Idle)
+    Note over Manager: Điều chỉnh giải pháp hoàn thiện
+    Manager->>User: Trình bày giải pháp cuối cùng kèm minh chứng
+```
+
+### Cách thức Triển khai cụ thể:
+- **Tận dụng Built-in `research`:** Dùng cho mọi tác vụ tìm kiếm codebase hoặc đọc file lớn. Session tìm kiếm thô sẽ tự giải phóng khi subagent hoàn thành, giữ cho context chính cực sạch.
+- **Định nghĩa Custom `critic` qua `define_subagent`:**
+  - Thiết lập `system_prompt` hướng tới việc rà soát lỗi logic, stress-test các giả thuyết.
+  - Cấu hình **Read-Only** tools để bảo vệ codebase khỏi việc ghi đè vô ý.
+- **Định nghĩa Custom `safety-router`:** Phân loại các hành động có side-effect (ví dụ: mutated file, write database, outbound network). Sử dụng tính năng interruption của Antigravity để dừng luồng và xin phê duyệt từ user (Approval Boundary).
+- **Giao tiếp qua Tin nhắn (Inter-Agent Messaging):** Tận dụng trạng thái `Idle` và cơ chế thức tỉnh khi nhận tin nhắn để duy trì các sub-agents chạy ngầm trong suốt phiên làm việc, tránh khởi tạo lại nhiều lần gây hao phí token.
+
+---
+
+## 4. Kịch bản Kiểm thử & Đánh giá (Verification Cases)
+
+| Kịch bản | Cách thức thực thi | Tiêu chí Đạt (Pass Criteria) |
+| :--- | :--- | :--- |
+| **Deep Research & Code Review** | Manager spawn `research` để tìm codebase, sau đó spawn 2 `critic` song song để review độc lập. | Báo cáo cuối đầy đủ bằng chứng, không lẫn log thô của `research`. |
+| **Approval Boundary Test** | Thực thi một câu lệnh ghi đè file nhạy cảm. | Hệ thống bắt buộc phải kích hoạt `safety-router`, tạm dừng tiến trình và hiển thị yêu cầu Approve rõ ràng cho User. |
+| **Wise Teacher Checkpoint** | Kích hoạt `/teach` sau một gate lớn. | Tạo thành công checklist học tập tại `.brain/teach_checklist.md`, hỏi user restate và đặt câu hỏi qua `AskUserQuestion`. |

package/docs/history/implementation_plan.v1.md

@@ -0,0 +1,58 @@
+# Add Game Development Skills (Unity, Godot, Expo)
+
+Implement dedicated game development skills inside `main-awf/skills` to enhance the orchestrator's capability in building games using Unity, Godot, and Expo.
+
+## User Review Required
+
+> [!NOTE]
+> All new skills will be created directly in `skills/` of `main-awf` workspace and then deployed to `~/.gemini/antigravity` via `awkit install`.
+
+## Proposed Changes
+
+### AWKit Skills
+
+---
+
+#### [NEW] [unity-game-development/SKILL.md](file:///Users/trungkientn/Dev/NodeJS/main-awf/skills/unity-game-development/SKILL.md)
+Contains high-density instructions for Unity game development, enforcing:
+- C# coding style (PascalCase public, camelCase private, `m_` fields prefix).
+- Component-based architecture and ScriptableObjects for data-driven game structures.
+- Performance optimization: avoiding `Find`/`GetComponent` in hot paths (`Update()`), caching, object pooling.
+- Separate Editor code via `#if UNITY_EDITOR`.
+- Direct Unity MCP server integration.
+
+#### [NEW] [godot-game-development/SKILL.md](file:///Users/trungkientn/Dev/NodeJS/main-awf/skills/godot-game-development/SKILL.md)
+Contains guidelines for Godot 4.x game development, enforcing:
+- Godot 4 API standards (rejecting Godot 3 syntax).
+- GDScript style preferences (`@export`, `@onready`, `await` signals).
+- Composition-first scene tree structure over deep class inheritance.
+- Signal connection best practices (`signal.connect(callback)`).
+- Physics and locomotion handling via parameterless `move_and_slide()`.
+
+#### [NEW] [expo-game-development/SKILL.md](file:///Users/trungkientn/Dev/NodeJS/main-awf/skills/expo-game-development/SKILL.md)
+Contains instructions for Expo/React Native game development, covering:
+- High-frequency drawing techniques (React Native Skia, Expo GL/Three.js).
+- State optimization: keeping physics/game tick loop decoupled from heavy React re-renders.
+- User input handling (React Native Gesture Handler).
+- Game loop implementations using `requestAnimationFrame`.
+- Asset management and sound effects via `expo-av`.
+
+---
+
+#### [MODIFY] [CATALOG.md](file:///Users/trungkientn/Dev/NodeJS/main-awf/skills/CATALOG.md)
+Add the three new skills to the active skills table.
+
+#### [MODIFY] [TRIGGER_INDEX.md](file:///Users/trungkientn/Dev/NodeJS/main-awf/skills/TRIGGER_INDEX.md)
+Register keywords and triggers for the new game skills.
+
+---
+
+## Verification Plan
+
+### Automated Verification
+- Run `awkit status` to inspect mapping diffs.
+- Deploy to runtime using `awkit install`.
+- Verify CLI integration and syntax using `awkit doctor`.
+
+### Manual Verification
+- Ask the user to verify the added skills locally or confirm availability in future workspace tasks.

package/docs/history/memoizedfibonacci_spec.v1.md

@@ -0,0 +1,127 @@
+# Technical Specification — MemoizedFibonacci
+
+## Revision History
+
+| Version | Date | Author | Description |
+| :--- | :--- | :--- | :--- |
+| 1.0 | 2026-06-22 | Antigravity Orchestrator | Initial technical design with Mermaid diagram, class architecture, and caching strategy. |
+
+---
+
+## 1. System Architecture
+
+The `MemoizedFibonacci` feature consists of three primary layers:
+1. **API & Interface Layer:** Exposes synchronous and asynchronous methods to users.
+2. **LRU Cache Layer:** Manages in-memory storage of computed sequences with automatic eviction based on Least Recently Used patterns.
+3. **Computation Engine:** Performs iterative sequence calculations to prevent call stack overflow, handles dynamic upgrading to `BigInt` for large numbers, and schedules asynchronous chunks for heavy inputs.
+
+---
+
+## 2. API Design & Core Interface
+
+```typescript
+interface FibonacciConfig {
+  maxCacheSize?: number;      // Maximum number of entries in the cache (default: 1000)
+  useBigInt?: boolean;        // Force BigInt computation even for small inputs (default: false)
+  asyncThreshold?: number;    // Input size to trigger asynchronous execution (default: 50000)
+}
+
+interface CacheStats {
+  hits: number;
+  misses: number;
+  size: number;
+  evictions: number;
+}
+
+class MemoizedFibonacci {
+  private cache: Map<number, number | bigint>;
+  private lruList: number[]; // Tracks usage order (least recently used at the front)
+  private config: Required<FibonacciConfig>;
+  private stats: CacheStats;
+
+  constructor(config?: FibonacciConfig);
+
+  /**
+   * Calculates Fibonacci of n. Automatically picks sync/async mode based on threshold.
+   */
+  public async calculate(n: number): Promise<number | bigint>;
+
+  /**
+   * Synchronously calculates Fibonacci of n.
+   * Throws warning/error if n is larger than asyncThreshold.
+   */
+  public calculateSync(n: number): number | bigint;
+
+  /**
+   * Retreives cache usage statistics.
+   */
+  public getStats(): CacheStats;
+
+  /**
+   * Clears all cache entries and metrics.
+   */
+  public clearCache(): void;
+
+  /**
+   * Private helper implementing iterative Fibonacci sequence.
+   */
+  private computeIterative(n: number, isBigInt: boolean): number | bigint;
+}
+```
+
+---
+
+## 3. Detailed Logic Flow (Mermaid Diagram)
+
+The following diagram illustrates the routing, validation, precision selection, and caching logic:
+
+```mermaid
+graph TD
+    A[Start: Calculate F(n)] --> B{Validate input n >= 0}
+    B -- No --> C[Throw Error: Invalid Input]
+    B -- Yes --> D{Check Cache for n}
+    D -- Hit (Yes) --> E[Update LRU Order]
+    E --> F[Return Cached Value]
+    D -- Miss (No) --> G{Check Precision Mode: n > 78 or useBigInt}
+    G -- Standard Number (n <= 78) --> H[Compute using standard arithmetic]
+    G -- BigInt (n > 78) --> I{Is n >= asyncThreshold?}
+    I -- No (Sync BigInt) --> J[Compute iteratively using BigInt]
+    I -- Yes (Async BigInt) --> K[Offload computation to worker thread / chunked loop]
+    K --> L[Iterate asynchronously without blocking event loop]
+    H --> M[Store Result in Cache]
+    J --> M
+    L --> M
+    M --> N{Cache Size > maxCacheSize?}
+    N -- Yes --> O[Evict Least Recently Used entry]
+    O --> P[Return Computed Result]
+    N -- No --> P
+```
+
+---
+
+## 4. Key Implementation Mechanics
+
+### 4.1 LRU Eviction Implementation
+To avoid linear scanning for evictions, the cache is backed by:
+- A `Map` mapping `n` to the value (either `Number` or `BigInt`).
+- A doubly-linked list or ordered array (`lruList`) tracking usage keys. On a cache hit, the key is moved to the end. On a cache insertion, if the map exceeds `maxCacheSize`, the key at the front of `lruList` is deleted from both the list and the map.
+
+### 4.2 Precision Safeguards
+- **Standard Float Limits:** Standard numbers in JavaScript lose precision above $F(78)$ ($F(78) = 8944394323791464$, whereas $F(79) = 14472334024559020$ which exceeds `Number.MAX_SAFE_INTEGER`).
+- **Automatic BigInt Upgrade:** If the class configuration is not explicitly set, inputs $n \ge 79$ automatically upgrade execution to `BigInt` mode.
+
+### 4.3 Async Slicing / Non-blocking Loop
+For large values of $n$ (e.g. $n \ge 500,000$), calculating Fibonacci in a single synchronous loop blocks the JS single-threaded event loop for several milliseconds. The `MemoizedFibonacci` class handles this via:
+- **Chunked execution:** Splitting the loop into chunks of 10,000 iterations and yielding back control using `setImmediate` or `setTimeout(..., 0)` to allow standard event-loop ticks to execute.
+- Alternatively, utilizing **Worker Threads** via `node:worker_threads` for CPU offloading in Node.js environments.
+
+---
+
+## 5. Error Handling & Edge Cases
+
+| Condition | System Response |
+| :--- | :--- |
+| Negative Input ($n < 0$) | Throws `RangeError: Input must be a non-negative integer.` |
+| Floating point Input (e.g., $n = 3.5$) | Automatically truncated using `Math.floor(n)` with a console warning, or throws a `TypeError`. |
+| Out of Memory Risk ($n > 1,000,000$) | Rejects promise with a warning about resource exhaustion unless a `force` flag is set. |
+| Cache Collision (Standard vs BigInt) | Values in cache are stored with consistent type based on configuration to avoid mixed-type arithmetic downstream. |

package/docs/specs/greetingapp_spec.md

@@ -0,0 +1,97 @@
+# Technical Specification - GreetingApp
+
+## Revision History
+| Version | Date | Description | Author |
+|---|---|---|---|
+| v1.0 | 2026-06-22 | Technical specification for GreetingApp | Antigravity Orchestrator |
+
+---
+
+## 1. System Architecture
+The GreetingApp consists of three major components:
+1. **Greeting Engine (Core):** Performs validation, detects time-of-day categories, maps to localization files, and builds the string.
+2. **Storage Layer:** A lightweight JSON/SQLite file logger to record history.
+3. **Interfaces:**
+   - CLI Controller: Handles flags and standard output formatting.
+   - REST Controller: Express.js routes and JSON responses.
+
+## 2. Detailed Component Specs
+
+### 2.1 Greeting Engine (`core/GreetingEngine`)
+- **Input:**
+  - `name`: string (optional, default: "Guest")
+  - `lang`: string (optional, default: "en")
+  - `timezone`: string (optional, default: system timezone)
+- **Time Periods:**
+  - `Morning`: 05:00 - 11:59
+  - `Afternoon`: 12:00 - 17:59
+  - `Evening`: 18:00 - 21:59
+  - `Night`: 22:00 - 04:59
+- **Localization Files (`locales/*.json`):**
+  - Example `en.json`:
+    ```json
+    {
+      "morning": "Good morning, {name}!",
+      "afternoon": "Good afternoon, {name}!",
+      "evening": "Good evening, {name}!",
+      "night": "Good night, {name}!"
+    }
+    ```
+
+### 2.2 Storage Schema
+A SQLite or JSON lines file containing:
+- `id`: UUID / Auto-increment integer
+- `name`: String
+- `language`: String
+- `timestamp`: ISO-8601 string
+- `greeting_message`: String
+
+## 3. Interface Design
+
+### 3.1 CLI Interface
+`awkit greet [options]`
+- `--name, -n`: Name of the user to greet.
+- `--lang, -l`: Language code (en, vi, ja).
+- `--help, -h`: Show usage description.
+
+### 3.2 REST API Specification
+`GET /api/greet`
+- **Query Parameters:**
+  - `name` (string)
+  - `lang` (string)
+- **Response (200 OK):**
+  - Content-Type: `application/json`
+  - Body:
+    ```json
+    {
+      "status": "success",
+      "data": {
+        "message": "Good morning, Alice!",
+        "name": "Alice",
+        "lang": "en",
+        "timestamp": "2026-06-22T05:35:15Z"
+      }
+    }
+    ```
+
+## 4. Error Handling
+- **Invalid Language:** Fallback to `en` and log warning.
+- **Invalid Input characters:** Sanitize inputs to prevent command line injection or XSS (on API side).
+
+## 5. Flow Diagram
+```mermaid
+graph TD
+    A[Start Request] --> B{Validate Inputs}
+    B -- Invalid --> C[Use Defaults: Guest/en]
+    B -- Valid --> D[Resolve User Local Time]
+    C --> D
+    D --> E{Determine Time of Day}
+    E -->|05:00-11:59| F[Morning Template]
+    E -->|12:00-17:59| G[Afternoon Template]
+    E -->|18:00-21:59| H[Evening Template]
+    E -->|22:00-04:59| I[Night Template]
+    F & G & H & I --> J[Replace {name} in Template]
+    J --> K[Log Transaction to History DB]
+    K --> L[Format Output CLI/REST]
+    L --> M[End Request]
+```

package/docs/specs/memoizedfibonacci_spec.md

@@ -0,0 +1,211 @@
+# Technical Specification — MemoizedFibonacci
+
+## Revision History
+
+| Version | Date | Author | Description |
+| :--- | :--- | :--- | :--- |
+| 1.0 | 2026-06-22 | Antigravity Orchestrator | Initial technical design with Mermaid diagram, class architecture, and caching strategy. |
+| 1.1 | 2026-06-22 | Antigravity Orchestrator | Refined LRU caching mechanism using ES6 Map insertion ordering. Added explicit detail on Async Slicing and Testing Strategy. |
+
+---
+
+## 1. System Architecture
+
+The `MemoizedFibonacci` feature consists of three primary layers:
+1. **API & Interface Layer:** Exposes synchronous and asynchronous methods to users.
+2. **LRU Cache Layer:** Manages in-memory storage of computed sequences with automatic eviction based on Least Recently Used patterns.
+3. **Computation Engine:** Performs iterative sequence calculations to prevent call stack overflow, handles dynamic upgrading to `BigInt` for large numbers, and schedules asynchronous chunks for heavy inputs.
+
+---
+
+## 2. API Design & Core Interface
+
+```typescript
+interface FibonacciConfig {
+  maxCacheSize?: number;      // Maximum number of entries in the cache (default: 1000)
+  useBigInt?: boolean;        // Force BigInt computation even for small inputs (default: false)
+  asyncThreshold?: number;    // Input size to trigger asynchronous execution (default: 50000)
+}
+
+interface CacheStats {
+  hits: number;
+  misses: number;
+  size: number;
+  evictions: number;
+}
+
+class MemoizedFibonacci {
+  // Built-in ES6 Map maintains insertion order.
+  // By deleting and re-inserting a key on access, the most recently used keys move to the end.
+  // The first key in map.keys() represents the Least Recently Used (LRU) element.
+  private cache: Map<number, number | bigint>;
+  private config: Required<FibonacciConfig>;
+  private stats: CacheStats;
+
+  constructor(config?: FibonacciConfig);
+
+  /**
+   * Calculates Fibonacci of n. Automatically picks sync/async mode based on threshold.
+   * Returns a Promise resolving to number or bigint.
+   */
+  public calculate(n: number): Promise<number | bigint>;
+
+  /**
+   * Synchronously calculates Fibonacci of n.
+   * Throws RangeError if n exceeds asyncThreshold to protect the thread.
+   */
+  public calculateSync(n: number): number | bigint;
+
+  /**
+   * Checks if the value for n is currently cached.
+   */
+  public isCached(n: number): boolean;
+
+  /**
+   * Dynamically updates the cache capacity limit. Evicts items if size exceeds new limit.
+   */
+  public setMaxCacheSize(size: number): void;
+
+  /**
+   * Retrieves cache usage statistics.
+   */
+  public getStats(): CacheStats;
+
+  /**
+   * Clears all cache entries and resets statistics.
+   */
+  public clearCache(): void;
+
+  /**
+   * Internal helper implementing iterative computation.
+   */
+  private computeIterative(n: number, isBigInt: boolean): number | bigint;
+
+  /**
+   * Internal helper performing non-blocking chunked computation.
+   */
+  private computeAsyncChunked(n: number, chunkSize: number): Promise<bigint>;
+}
+```
+
+---
+
+## 3. Detailed Logic Flow (Mermaid Diagram)
+
+The following diagram illustrates the routing, validation, precision selection, and caching logic:
+
+```mermaid
+graph TD
+    A[Start: Calculate F(n)] --> B{Validate input n >= 0}
+    B -- No --> C[Throw RangeError: Invalid Input]
+    B -- Yes --> D{Check Cache for n}
+    
+    D -- Hit (Yes) --> E[Update Map Insertion Order: Delete & Re-insert]
+    E --> F[Increment Hit Metric]
+    F --> G[Return Cached Value]
+    
+    D -- Miss (No) --> H[Increment Miss Metric]
+    H --> I{Check Precision Mode: n > 78 or useBigInt}
+    
+    I -- Standard Number (n <= 78) --> J[Compute iteratively using standard Number]
+    I -- BigInt (n > 78) --> K{Is n >= asyncThreshold?}
+    
+    K -- No (Sync BigInt) --> L[Compute iteratively using BigInt]
+    K -- Yes (Async BigInt) --> M[Invoke computeAsyncChunked]
+    
+    M --> N[Loop in chunks of size 10,000 using setImmediate]
+    N --> O[Yield control back to Event Loop after each chunk]
+    
+    J --> P[Store Result in Cache]
+    L --> P
+    O --> P
+    
+    P --> Q{Cache Size > maxCacheSize?}
+    Q -- Yes --> R[Evict map.keys.next.value oldest entry]
+    R --> S[Increment Eviction Metric]
+    S --> T[Return Computed Result]
+    Q -- No --> T
+```
+
+---
+
+## 4. Key Implementation Mechanics
+
+### 4.1 LRU Eviction Implementation (ES6 Map)
+Instead of managing a separate `lruList` array (which incurs $O(N)$ lookup/splice operations), the implementation relies entirely on the ordered property of JavaScript's `Map`.
+* **Read (Cache Hit):**
+  ```javascript
+  const value = this.cache.get(key);
+  this.cache.delete(key);
+  this.cache.set(key, value); // Re-inserts at the end of the Map
+  ```
+* **Write (Cache Miss & Capacity Exceeded):**
+  ```javascript
+  this.cache.set(key, value);
+  if (this.cache.size > this.config.maxCacheSize) {
+    const oldestKey = this.cache.keys().next().value;
+    this.cache.delete(oldestKey); // Deletes the oldest insertion
+    this.stats.evictions++;
+  }
+  ```
+This architecture yields highly efficient $O(1)$ operations for both cache lookup and replacement.
+
+### 4.2 Precision Safeguards & Double Limits
+- **Standard Float Limits:** Standard numbers in JavaScript lose precision above $F(78)$ ($F(78) = 8944394323791464$, whereas $F(79) = 14472334024559020$ which exceeds `Number.MAX_SAFE_INTEGER`).
+- **Automatic BigInt Upgrade:** If the class configuration is not explicitly set, inputs $n \ge 79$ automatically upgrade execution to `BigInt` mode.
+
+### 4.3 Async Slicing / Non-blocking Loop
+For large values of $n$ (e.g. $n \ge 100,000$), calculating Fibonacci in a single synchronous loop blocks the JS single-threaded event loop.
+We employ a chunked calculation pattern:
+```javascript
+private async computeAsyncChunked(n: number, chunkSize: number = 10000): Promise<bigint> {
+  let prev = 0n;
+  let curr = 1n;
+  let i = 2;
+
+  const runChunk = (): Promise<bigint> => {
+    return new Promise((resolve) => {
+      setImmediate(() => {
+        const target = Math.min(i + chunkSize, n + 1);
+        for (; i < target; i++) {
+          const next = prev + curr;
+          prev = curr;
+          curr = next;
+        }
+        if (i <= n) {
+          resolve(runChunk()); // Recursively queue the next chunk
+        } else {
+          resolve(curr);
+        }
+      });
+    });
+  };
+
+  return runChunk();
+}
+```
+
+---
+
+## 5. Error Handling & Edge Cases
+
+| Condition | System Response |
+| :--- | :--- |
+| Negative Input ($n < 0$) | Throws `RangeError: Input must be a non-negative integer.` |
+| Floating point Input (e.g., $n = 3.5$) | Throws `TypeError: Input must be an integer.` |
+| Maximum Guardrail Breach ($n > 1,000,000$) | Throws `RangeError: Calculation size exceeds maximum guardrail of 1,000,000.` |
+| Sync Call beyond Threshold ($n > asyncThreshold$) | Throws `RangeError: Input exceeds asyncThreshold. Use calculate() instead.` |
+
+---
+
+## 6. Testing Strategy
+
+### 6.1 Unit Tests
+* **Core Calculations:** Verify $F(0) = 0$, $F(1) = 1$, $F(10) = 55$, and $F(78) = 8944394323791464$.
+* **BigInt Accuracy:** Verify $F(79)$ is correctly calculated as `14472334024559020n` (with tailing `n` specifying bigint).
+* **Caching Performance:** Retrieve $F(50)$ twice. The second call must trigger a cache hit and have a latency under 1 microsecond.
+* **LRU Eviction:** Set cache limit to 3. Populate cache with keys 1, 2, 3. Read key 1 (making it most recently used). Insert key 4. Verify key 2 is evicted.
+
+### 6.2 Performance & Memory Benchmarks
+* **Sync vs Async Threshold:** Test the threshold boundary. Verify that calling `calculate(49999)` completes synchronously within milliseconds, and `calculate(50001)` returns a Promise and yields event loop control.
+* **Leak Testing:** Execute calculation loop of random values up to $n = 10,000$ for 100,000 iterations. Verify heap memory remains flat (no leakage outside the bounds of `maxCacheSize`).

package/package.json

@@ -1,9 +1,12 @@
 {
   "name": "@leejungkiin/awkit",
-  "version": "1.7.1",
+  "version": "1.7.5",
   "description": "Antigravity Workflow Kit v1.6 Unified AI agent orchestration system with Mindful Checkpoints.",
   "main": "bin/awk.js",
   "private": false,
+  "publishConfig": {
+    "access": "public"
+  },
   "bin": {
     "awkit": "bin/awk.js",
     "ag": "bin/awk.js"