nav-stats 属于 Supernavigator 工具集，用途是把 Navigator 的会话效率量化成可读、可分享的报告。
用途：当用户说“show my stats”“show session stats”“show metrics”，或询问“how efficient am I”“how much did I save”“efficiency report”“show impact”“prove Navigator works”时调用。若会话刚开始（少于 5 条消息）、项目未初始化 Navigator，或用户只问某一具体指标，则不应调用。
主要能力：报告包含 token 使用（文档实际加载量、全部文档基线、节省量与节省百分比）、缓存效率（来自 OpenTelemetry）、上下文占用百分比、0-100 的效率评分，以及估算节省时间（按每 1k token 约 6 秒计算）。评分由 efficiency_scorer.py 依据 token 节省（40 分）、缓存效率（30 分）、上下文占用（30 分）计算；报告由 report_formatter.py 输出为 ASCII 图形。还会按评分、上下文占用、缓存效率给出针对性建议。
必要用法：先确认存在 .agent/DEVELOPMENT-README.md，否则提示未初始化；再检查 scripts/session-stats.sh 是否存在，否则提示需 Navigator v3.5.0+。随后执行 bash scripts/session-stats.sh，该脚本输出 BASELINE_TOKENS、LOADED_TOKENS、TOKENS_SAVED、SAVINGS_PERCENT、EFFICIENCY_SCORE、CACHE_EFFICIENCY、CONTEXT_USAGE_PERCENT、TIME_SAVED_MINUTES 等变量。之后可用 source <(bash scripts/session-stats.sh) 载入变量，并调用效率评分与报告格式化脚本。
适用场景：希望看到本次会话节省了多少 token、验证懒加载策略是否生效、判断上下文窗口是否健康，以及通过截图分享效率结果的用户。
限制：依赖项目已初始化 Navigator、存在对应脚本与足够会话消息；缓存效率依赖 OpenTelemetry 数据；报告中的 token 加载量与节省时间均为估算值。若缺少所需条件，脚本会提示先初始化或升级版本。其余未在资料中说明的功能、收费与平台信息暂未提供。