feat: fix Knowledge Base module and add pager-style viewer

## Fixed
- GitHub API 403 rate limiting error when browsing documentation
  - Added GitHub token authentication (GITHUB_TOKEN/GH_TOKEN env vars)
  - Improved error messages with rate limit info and reset time
  - Increased limit from 60 to 5000 requests/hour with token

## Added
- Pager-style document viewer (vim/journalctl/less style)
  - Natural scrolling with arrow keys, Space, j/k, q to quit
  - Better reading experience for long documents
  - Auto-fallback to direct output if pager unavailable
- Re-read document option after viewing
- Environment variable support for PAGER customization

## Improved
- Enhanced error handling with detailed rate limit diagnostics
- Better user feedback when rate limits are reached
- Clear instructions for resolving authentication issues

## Updated
- README.md with GitHub token configuration instructions
- CHANGELOG.md with complete v1.0.5 release notes
- Version bumped to 1.0.5

Fixes #1: Knowledge Base 403 error
Fixes #2: Hard to read documents before pager implementation

Author: m1ngsama

CHANGELOG.md

@@ -1,5 +1,53 @@
 # CHANGELOG
 
+## [1.0.5] - 2025-12-10
+
+### Fixed
+- **Knowledge Base 403 Error**: Resolved GitHub API rate limiting issue that caused 403 errors when browsing documentation
+  - Added GitHub token authentication support via `GITHUB_TOKEN` or `GH_TOKEN` environment variables
+  - Improved error messages with rate limit information and reset time
+  - Increased rate limit from 60 to 5000 requests per hour when using a token
+
+### Added
+- **Pager-Style Document Viewer**: Documents now open in a pager (similar to vim/journalctl/less)
+  - Natural scrolling navigation with arrow keys, Space, j/k (vim-style), and q to quit
+  - Content doesn't flood the terminal anymore
+  - Better reading experience for long documents
+  - Automatic fallback to direct output if pager is unavailable
+- **Re-read Document Option**: Added ability to re-read a document after viewing without going back to the list
+- **Environment Variable Support**:
+  - `GITHUB_TOKEN` or `GH_TOKEN` for GitHub API authentication
+  - `PAGER` for custom pager selection (defaults to `less`)
+
+### Improved
+- Enhanced error handling with detailed rate limit diagnostics
+- Better user feedback when rate limits are reached
+- Clearer instructions for resolving authentication issues
+
+### Technical Details
+- Added `displayInPager()` function for spawning system pager processes
+- Enhanced `fetchGitHubDirectory()` with conditional token authentication
+- Updated documentation viewer workflow for better UX
+
+## [1.0.4] - 2025-12-10
+
+### Enhanced
+- **Smooth Slogan Animation**: Implemented true color interpolation for buttery smooth gradient animation
+  - Increased frame rate from 24 to 60 FPS for ultra-smooth motion
+  - Changed easing from cubic to sine wave for more natural transitions
+  - Dynamically generate gradients per frame instead of using pre-defined set
+  - Eliminates staggered/jumping effect in the slogan text animation
+
+### Technical Details
+- Added `hexToRgb()`, `rgbToHex()`, and `interpolateColor()` functions for mathematical color blending
+- Implemented `easeInOutSine()` easing function for smooth acceleration/deceleration
+- Each frame now uses unique, mathematically interpolated colors
+
+## [1.0.3] - 2025-11-27
+
+### Changed
+- Version alignment and bug fixes
+
 ## [1.0.2] - 2025-11-27
 
 ### Added

README.md

@@ -13,9 +13,10 @@ NBTCA Prompt is a minimalist command-line interface tool designed for the Comput
 
 - View upcoming association events (30-day calendar)
 - Access repair service information
-- Browse technical documentation from terminal
+- Browse technical documentation from terminal with pager support (vim/journalctl style)
 - Quick links to official website and GitHub
 - Minimalist design with maximum terminal compatibility
+- Smooth gradient animations for enhanced visual experience
 
 ## Installation
 
@@ -131,11 +132,25 @@ src/
 
 The knowledge base viewer features:
 
-- Direct GitHub repository access
+- Direct GitHub repository access with authentication support
+- Pager-style document reading (similar to vim/journalctl/less)
 - VitePress syntax cleaning
-- Terminal Markdown rendering
+- Terminal Markdown rendering with color support
 - Browser fallback option
 - Directory tree navigation
+- Improved error handling with rate limit detection
+
+### GitHub Token Configuration (Optional)
+
+To avoid GitHub API rate limits when browsing documentation, you can set a GitHub token:
+
+```bash
+export GITHUB_TOKEN="your_github_token_here"
+# or
+export GH_TOKEN="your_github_token_here"
+```
+
+Without a token, you have 60 requests per hour. With a token, you get 5000 requests per hour.
 
 ### Supported Formats
 
@@ -163,6 +178,10 @@ ASCII-based UI elements ensure rendering on any terminal emulator.
 
 ## Common Issues
 
+### Q: Getting 403 error when browsing documentation?
+
+A: This is due to GitHub API rate limiting. Set a `GITHUB_TOKEN` environment variable to increase your rate limit from 60 to 5000 requests per hour. See the [GitHub Token Configuration](#github-token-configuration-optional) section above.
+
 ### Q: Auto-restart when using `pnpm run dev:watch`?
 
 A: This is expected behavior. Use `pnpm run dev` for interactive testing.
@@ -171,6 +190,10 @@ A: This is expected behavior. Use `pnpm run dev` for interactive testing.
 
 A: Select the Exit option from menu, or press Ctrl+C.
 
+### Q: How to navigate documents in the pager?
+
+A: Use arrow keys, Space (page down), 'j/k' (vim-style), or 'q' to quit the pager.
+
 ### Q: Changes not reflected?
 
 A: If using `pnpm start`, rebuild with `pnpm run build` first.
@@ -206,6 +229,25 @@ MIT License - See LICENSE file for details
 
 ## Changelog
 
+### v1.0.5 (2025-12-10)
+
+- **Fixed**: Knowledge Base 403 error due to GitHub API rate limiting
+- **Added**: GitHub token authentication support (GITHUB_TOKEN/GH_TOKEN)
+- **Added**: Pager-style document viewer (vim/journalctl/less style)
+- **Added**: "Re-read document" option after viewing
+- **Improved**: Better error messages with rate limit information
+- **Improved**: Document reading experience with scroll navigation
+
+### v1.0.4 (2025-12-10)
+
+- **Enhanced**: Smooth slogan animation with true color interpolation
+- **Improved**: 60 FPS animation with sine easing for natural transitions
+- **Technical**: Added hexToRgb, rgbToHex, and interpolateColor functions
+
+### v1.0.3 (2025-11-27)
+
+- Version alignment and bug fixes
+
 ### v1.0.1 (2025-11-27)
 
 - Added terminal documentation viewer

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nbtca/prompt",
-  "version": "1.0.4",
+  "version": "1.0.5",
   "type": "module",
   "main": "dist/index.js",
   "bin": {

src/features/docs.ts

@@ -10,6 +10,7 @@ import chalk from 'chalk';
 import open from 'open';
 import inquirer from 'inquirer';
 import { error, info, success, warning } from '../core/ui.js';
+import { spawn } from 'child_process';
 
 // 配置marked使用终端渲染器
 marked.setOptions({
@@ -26,6 +27,12 @@ const GITHUB_REPO = {
   branch: 'main'
 };
 
+/**
+ * GitHub Token (可选 - 用于避免 API 速率限制)
+ * 从环境变量读取，如果没有则使用未认证请求
+ */
+const GITHUB_TOKEN = process.env['GITHUB_TOKEN'] || process.env['GH_TOKEN'];
+
 /**
  * 文档结构类型
  */
@@ -56,12 +63,19 @@ async function fetchGitHubDirectory(path: string = ''): Promise<DocItem[]> {
   const url = `https://api.github.com/repos/${GITHUB_REPO.owner}/${GITHUB_REPO.repo}/contents/${path}?ref=${GITHUB_REPO.branch}`;
 
   try {
+    const headers: any = {
+      'Accept': 'application/vnd.github.v3+json',
+      'User-Agent': 'NBTCA-CLI'
+    };
+
+    // 如果有 GitHub Token，添加认证头以避免速率限制
+    if (GITHUB_TOKEN) {
+      headers['Authorization'] = `Bearer ${GITHUB_TOKEN}`;
+    }
+
     const response = await axios.get(url, {
       timeout: 10000,
-      headers: {
-        'Accept': 'application/vnd.github.v3+json',
-        'User-Agent': 'NBTCA-CLI'
-      }
+      headers
     });
 
     return response.data
@@ -90,6 +104,17 @@ async function fetchGitHubDirectory(path: string = ''): Promise<DocItem[]> {
         return a.name.localeCompare(b.name);
       });
   } catch (err: any) {
+    // 提供更详细的错误信息
+    if (err.response?.status === 403) {
+      const rateLimitRemaining = err.response.headers['x-ratelimit-remaining'];
+      const rateLimitReset = err.response.headers['x-ratelimit-reset'];
+
+      if (rateLimitRemaining === '0') {
+        const resetDate = new Date(parseInt(rateLimitReset) * 1000);
+        throw new Error(`GitHub API 速率限制已达上限，将在 ${resetDate.toLocaleTimeString()} 重置。\n提示: 设置 GITHUB_TOKEN 环境变量可获得更高的速率限制。`);
+      }
+      throw new Error(`GitHub API 拒绝访问 (403)。\n提示: 尝试设置 GITHUB_TOKEN 环境变量。`);
+    }
     throw new Error(`无法获取目录内容: ${err.message}`);
   }
 }
@@ -231,6 +256,50 @@ async function browseDirectory(dirPath: string = ''): Promise<void> {
   }
 }
 
+/**
+ * 使用系统pager (less/more) 显示内容
+ * 提供类似vim/journalctl的阅读体验
+ */
+async function displayInPager(content: string, title: string): Promise<boolean> {
+  return new Promise((resolve) => {
+    // 检测可用的pager程序
+    const pager = process.env['PAGER'] || 'less';
+
+    // 为内容添加标题
+    const fullContent = `${chalk.cyan.bold(`>> ${title}`)}\n${chalk.gray('='.repeat(80))}\n\n${content}\n\n${chalk.gray('='.repeat(80))}\n${chalk.dim('End of document - Press q to quit')}\n`;
+
+    // less的参数: -R (支持颜色), -F (如果内容少于一屏则直接显示), -X (退出时不清屏)
+    const lessArgs = ['-R', '-F', '-X'];
+
+    try {
+      const child = spawn(pager, lessArgs, {
+        stdio: ['pipe', 'inherit', 'inherit'],
+        shell: true
+      });
+
+      // 将内容写入pager的stdin
+      child.stdin.write(fullContent);
+      child.stdin.end();
+
+      child.on('exit', (code) => {
+        resolve(code === 0);
+      });
+
+      child.on('error', () => {
+        // 如果pager失败，回退到直接输出
+        console.error(chalk.yellow('⚠ Pager不可用，使用标准输出'));
+        console.log(fullContent);
+        resolve(false);
+      });
+
+    } catch {
+      // 回退方案: 直接输出
+      console.log(fullContent);
+      resolve(false);
+    }
+  });
+}
+
 /**
  * 查看Markdown文件
  */
@@ -247,23 +316,15 @@ async function viewMarkdownFile(path: string): Promise<void> {
     // 提取标题
     const title = extractDocTitle(cleanedContent) || path.split('/').pop() || path;
 
-    console.clear();
-    console.log();
-    console.log(chalk.cyan.bold(`>> ${title}`));
-    console.log(chalk.gray(`   ${path}`));
-    console.log();
-    console.log(chalk.gray('='.repeat(80)));
-    console.log();
-
     // 渲染Markdown到终端
-    const rendered = marked(cleanedContent);
-    console.log(rendered);
-    console.log();
-    console.log(chalk.gray('='.repeat(80)));
-    console.log();
-    console.log(chalk.dim('  Note: Some features are only available in browser'));
-    console.log();
+    const rendered = await marked(cleanedContent);
+
+    console.log('\r' + ' '.repeat(60) + '\r'); // 清除加载提示
+
+    // 使用pager显示文档 (类似vim/journalctl的阅读体验)
+    await displayInPager(rendered, `${title}\n${chalk.gray(`   ${path}`)}`);
 
+    console.log(); // 添加空行
     success('文档加载完成');
     console.log();
 
@@ -275,13 +336,17 @@ async function viewMarkdownFile(path: string): Promise<void> {
         message: '选择操作:',
         choices: [
           { name: '[ <] Back to docs list', value: 'back' },
+          { name: '[ ↻] Re-read document', value: 'reread' },
           { name: '[ *] Open in browser', value: 'browser' }
         ]
       }
     ]);
 
     if (action === 'browser') {
       await openDocsInBrowser(path);
+    } else if (action === 'reread') {
+      // 重新阅读文档
+      await viewMarkdownFile(path);
     }
 
   } catch (err: any) {