fluffy-context 0.7.6 → 0.7.7

package/README.md

@@ -2,7 +2,7 @@
 
 本地优先、Agent 无关的 Context 与 Knowledge Runtime，帮助 AI 编程 Agent 保存任务状态、恢复工作上下文、复用已验证共识，并生成有界且可追溯的上下文输入。
 
-**当前版本：0.7.6**
+**当前版本：0.7.7**
 
 ```text
 checkpoint → orient → compile → expand → feedback → Agent continues
@@ -21,7 +21,7 @@ checkpoint → orient → compile → expand → feedback → Agent continues
 - `ctx compile`：生成带预算、来源和排除原因的 provider-neutral Context Manifest。
 - `ctx learn` / `ctx deadend`：记录可复用结论和失败方案，之后显式验证再用于普通检索。
 
-## 0.7.6 当前能力与边界
+## 0.7.7 当前能力与边界
 
 | 能力 | 当前支持 |
 | --- | --- |
@@ -32,16 +32,17 @@ checkpoint → orient → compile → expand → feedback → Agent continues
 | 文件活动 | 可选记录经过过滤的文件 metadata，并编译为 `activity` section |
 | Runtime | 本地 v2 Runtime、Git 观察、可选文件观察、自动唤醒和 fail-open 集成 |
 | 治理 | Knowledge/Deadend 的 candidate、verify、deprecate/obsolete、reject |
-| 集成 | Claude Code Hook、Claude Code 配置集成、MCP `context_orient`/`context_expand`、TypeScript Agent API |
+| 集成 | Claude Code Hook、Claude Code 配置集成、MCP `context_orient`/`context_expand`/`context_usage_report`、TypeScript Agent API |
+| 观测 | `ctx usage report`：只读统计资产、显式复用、操作趋势和 estimated token 投入 |
 
-以下能力**不属于 0.7.6**：
+以下能力**不属于 0.7.7**：
 
-- 没有 `ctx clean` 或 `ctx report`。
+- 没有 `ctx clean`；`ctx usage report` 是当前支持的只读观测命令。
 - 不自动创建 checkpoint、Note、Knowledge 或 Deadend。
 - 不自动把 Candidate 提升为 Verified。
 - 不提供模型总结、Embedding/向量检索、远程同步、多人协作或 Context merge。
 
-0.7.6 已支持 `context_expand`，用于按需取得已选候选的 `structured` 或 `evidence` 层；它是无状态、只读操作，不读取项目文件内容，也不自动记录 feedback。
+0.7.7 已支持 `context_expand`，用于按需取得已选候选的 `structured` 或 `evidence` 层；它是无状态、只读操作，不读取项目文件内容，也不自动记录 feedback。
 
 ## 快速开始
 
@@ -180,7 +181,7 @@ Manifest 主要包含：
 - `identity`：Manifest hash、选中 item hash 和 estimated token；
 - `text`：最终有界文本。
 
-0.7.6 的候选项提供：
+0.7.7 的候选项提供：
 
 ```text
 level: signal | summary | structured | evidence
@@ -212,6 +213,23 @@ Compiler 具有以下边界：
 - 普通查询默认只纳入适用且已验证的 Knowledge 和 Deadend；
 - `context_expand` 只读取已选候选的安全 metadata，不读取任意项目文件内容。
 
+### `ctx usage report`
+
+`usage report` 适合每周或每月复盘，不需要为每条 prompt 调用。它是只读的，基于 v1 文件和 v2 journal 派生统计，不创建事件、不修改 Context、Snapshot、Note 或 projection：
+
+```bash
+ctx usage report --days 30
+ctx usage report --month 2026-08 --granularity week
+ctx usage report --since 2026-08-01T00:00:00.000Z \
+  --until 2026-09-01T00:00:00.000Z \
+  --baseline-tokens 12000 --baseline-source manual
+ctx usage report --format ascii
+```
+
+默认输出稳定 JSON；`--format ascii` 仅输出终端仪表盘。报告展示资产总量和窗口增量、verified Knowledge/Deadend、显式 `record.used` reuse、orient/compile/expand/resume 操作统计、趋势以及上下文输出投入。
+
+报告中的 `chars / 4` 是 `estimated` token，不是真实 Provider token；Provider token 和计费金额当前为 `unavailable`。没有显式 `--baseline-tokens` 时，不会虚构 estimated savings、ROI 或 payback；查询命中、候选选择和编译纳入也不等于 reuse，只有显式 `record.used` 事件才计入复用。报告不替代 `ctx doctor`、`ctx journal verify` 或 Knowledge/Deadend 的人工治理。
+
 ## Knowledge、Deadend 和 Note
 
 ### Knowledge：记录可复用认知
@@ -423,7 +441,7 @@ ctx integrate claude install --apply
 ctx agent serve
 ```
 
-0.7.6 当前暴露以下工具：
+0.7.7 当前暴露以下工具：
 
 ```text
 context_orient       只读、有界地获取任务上下文
@@ -609,7 +627,7 @@ npm pack --dry-run --json
 
 ## 未来方向
 
-以下方向属于后续版本，不是 0.7.6 的当前能力：
+以下方向属于后续版本，不是 0.7.7 的当前能力：
 
 | 方向 | 目标 |
 | --- | --- |

package/dist/src/agent/api.d.ts

@@ -1,12 +1,16 @@
+import { type UsageInterface } from '../cognition/usage.js';
+import { type UsageReport, type UsageReportOptions } from '../cognition/usage-report.js';
 import type { AgentLoadOptions, AgentLoadResult, AgentSaveResult, CheckpointInput, ContextSearchOptions, ContextSearchResult } from '../runtime/types.js';
 import type { ContextOrientOptions, ContextOrientResult, ContextUseInput } from './types.js';
-import type { ContextExpandInput, ContextExpandResult } from '../compiler/types.js';
+import type { ContextExpandInput, ContextExpandResult, ContextCompileOptions, ContextManifest } from '../compiler/types.js';
 export declare function saveContext(startPath: string | undefined, input: CheckpointInput, options?: {
     minSaveIntervalMs?: number;
 }): Promise<AgentSaveResult>;
-export declare function contextExpand(startPath: string | undefined, input: ContextExpandInput): Promise<ContextExpandResult>;
-export declare function loadContext(startPath: string | undefined, options?: AgentLoadOptions): Promise<AgentLoadResult>;
-export declare function contextOrient(startPath: string | undefined, options?: ContextOrientOptions): Promise<ContextOrientResult>;
+export declare function contextExpand(startPath: string | undefined, input: ContextExpandInput, interfaceName?: UsageInterface): Promise<ContextExpandResult>;
+export declare function contextCompile(startPath: string | undefined, options?: ContextCompileOptions, interfaceName?: UsageInterface): Promise<ContextManifest>;
+export declare function loadContext(startPath: string | undefined, options?: AgentLoadOptions, interfaceName?: UsageInterface): Promise<AgentLoadResult>;
+export declare function contextOrient(startPath: string | undefined, options?: ContextOrientOptions, interfaceName?: UsageInterface | null): Promise<ContextOrientResult>;
+export declare function contextUsageReport(startPath: string | undefined, options?: UsageReportOptions): Promise<UsageReport>;
 export declare function recordContextUse(startPath: string | undefined, input: ContextUseInput): Promise<{
     recorded: boolean;
     eventId: string;

package/dist/src/agent/api.js

@@ -9,6 +9,9 @@ import { discoverV2Deadends, discoverV2Knowledge } from '../cognition/retrieval.
 import { discoverDeadends, discoverKnowledge, listDeadends } from '../runtime/knowledge.js';
 import { listNotes } from '../runtime/notes.js';
 import { expandContext } from '../compiler/expand.js';
+import { compileContext } from '../compiler/compile.js';
+import { withUsageTelemetry } from '../cognition/usage.js';
+import { buildUsageReport } from '../cognition/usage-report.js';
 function normalized(value) {
     return value.trim().toLocaleLowerCase();
 }
@@ -139,151 +142,163 @@ export async function saveContext(startPath, input, options = {}) {
     const projectRoot = await resolveProjectRoot(startPath);
     return { projectRoot, result: await checkpoint(projectRoot, input, options) };
 }
-export async function contextExpand(startPath, input) {
-    const projectRoot = await resolveProjectRoot(startPath);
-    return expandContext(projectRoot, input);
+export async function contextExpand(startPath, input, interfaceName = 'agent') {
+    return withUsageTelemetry(startPath, 'expand', 'agent', input, () => resolveProjectRoot(startPath).then((projectRoot) => expandContext(projectRoot, input)), interfaceName);
 }
-export async function loadContext(startPath, options = {}) {
-    const projectRoot = await resolveProjectRoot(startPath);
-    const result = await resume(projectRoot, options.contextId, options.maxChars ?? 4000);
-    const knowledge = options.query === undefined ? null : await discoverKnowledge(projectRoot, options.query, { scope: options.scope, maxChars: options.maxChars ?? 4000 });
-    const verifiedDeadends = await listDeadends(projectRoot);
-    return {
-        projectRoot,
-        context: result.context,
-        snapshot: result.snapshot,
-        resumeSummary: result.resumeSummary,
-        ...(options.includeDetails ? { details: result.details } : {}),
-        knowledge,
-        verifiedDeadendIds: verifiedDeadends.map((item) => item.deadendId),
-    };
+export async function contextCompile(startPath, options = {}, interfaceName = 'agent') {
+    return withUsageTelemetry(startPath, 'compile', 'agent', options, () => compileContext(startPath, options), interfaceName);
 }
-export async function contextOrient(startPath, options = {}) {
-    const projectRoot = await resolveProjectRoot(startPath);
-    const query = options.query === undefined ? null : options.query.trim();
-    if (query === '')
-        throw new Error('context orient query must not be empty');
-    let loaded;
-    try {
-        const v2 = await selectV2Orientation(projectRoot, options.contextId);
-        loaded = v2
-            ? await resumeSnapshot(projectRoot, v2.contextId, v2.snapshotId, options.maxChars ?? 4000)
-            : await resume(projectRoot, options.contextId, options.maxChars ?? 4000, { touchLastUsedAt: false });
-    }
-    catch (error) {
-        if (error instanceof Error && error.message === 'no active context found') {
-            return {
-                status: 'no_context',
-                projectRoot,
-                query,
-                context: null,
-                snapshot: null,
-                resumeSummary: null,
-                knowledge: emptyKnowledge(query ?? ''),
-                deadends: emptyDeadends(query ?? ''),
-                notes: [],
-                truncated: false,
-                explanation: {
-                    mode: 'v1-fallback',
-                    selection: 'v1',
-                    retrieval: { knowledge: {}, deadends: {} },
-                    truncation: { summary: false, knowledge: false, deadends: false, notes: false },
-                },
-            };
+export async function loadContext(startPath, options = {}, interfaceName = 'agent') {
+    return withUsageTelemetry(startPath, 'resume', 'agent', options, async () => {
+        const projectRoot = await resolveProjectRoot(startPath);
+        const result = await resume(projectRoot, options.contextId, options.maxChars ?? 4000);
+        const knowledge = options.query === undefined ? null : await discoverKnowledge(projectRoot, options.query, { scope: options.scope, maxChars: options.maxChars ?? 4000 });
+        const verifiedDeadends = await listDeadends(projectRoot);
+        return {
+            projectRoot,
+            context: result.context,
+            snapshot: result.snapshot,
+            resumeSummary: result.resumeSummary,
+            ...(options.includeDetails ? { details: result.details } : {}),
+            knowledge,
+            verifiedDeadendIds: verifiedDeadends.map((item) => item.deadendId),
+        };
+    }, interfaceName);
+}
+export async function contextOrient(startPath, options = {}, interfaceName = 'agent') {
+    const action = async () => {
+        const projectRoot = await resolveProjectRoot(startPath);
+        const query = options.query === undefined ? null : options.query.trim();
+        if (query === '')
+            throw new Error('context orient query must not be empty');
+        let loaded;
+        try {
+            const v2 = await selectV2Orientation(projectRoot, options.contextId);
+            loaded = v2
+                ? await resumeSnapshot(projectRoot, v2.contextId, v2.snapshotId, options.maxChars ?? 4000)
+                : await resume(projectRoot, options.contextId, options.maxChars ?? 4000, { touchLastUsedAt: false });
         }
-        throw error;
-    }
-    const v2 = await selectV2Orientation(projectRoot, options.contextId);
-    const notes = (await listNotes(projectRoot, {
-        contextId: loaded.context.id,
-        openOnly: true,
-        limit: v2 ? Number.MAX_SAFE_INTEGER : options.noteLimit ?? 20,
-        maxChars: options.maxChars ?? 4000,
-    })).filter((note) => !v2 || v2.noteIds.has(note.noteId)).slice(0, options.noteLimit ?? 20);
-    const v2Knowledge = query === null || !v2 ? null : discoverV2Knowledge(v2.retrieval, query, v2.currentGit, {
-        scope: options.scope,
-        limit: options.knowledgeLimit ?? 10,
-        maxChars: options.maxChars ?? 4000,
-    });
-    const v2Deadends = query === null || !v2 ? null : discoverV2Deadends(v2.retrieval, query, v2.currentGit, {
-        scope: options.scope,
-        limit: options.deadendLimit ?? 10,
-        maxChars: options.maxChars ?? 4000,
-    });
-    const applicableKnowledge = query === null
-        ? emptyKnowledge('')
-        : v2Knowledge?.result ?? await discoverKnowledge(projectRoot, query, {
+        catch (error) {
+            if (error instanceof Error && error.message === 'no active context found') {
+                return {
+                    status: 'no_context',
+                    projectRoot,
+                    query,
+                    context: null,
+                    snapshot: null,
+                    resumeSummary: null,
+                    knowledge: emptyKnowledge(query ?? ''),
+                    deadends: emptyDeadends(query ?? ''),
+                    notes: [],
+                    truncated: false,
+                    explanation: {
+                        mode: 'v1-fallback',
+                        selection: 'v1',
+                        retrieval: { knowledge: {}, deadends: {} },
+                        truncation: { summary: false, knowledge: false, deadends: false, notes: false },
+                    },
+                };
+            }
+            throw error;
+        }
+        const v2 = await selectV2Orientation(projectRoot, options.contextId);
+        const notes = (await listNotes(projectRoot, {
+            contextId: loaded.context.id,
+            openOnly: true,
+            limit: v2 ? Number.MAX_SAFE_INTEGER : options.noteLimit ?? 20,
+            maxChars: options.maxChars ?? 4000,
+        })).filter((note) => !v2 || v2.noteIds.has(note.noteId)).slice(0, options.noteLimit ?? 20);
+        const v2Knowledge = query === null || !v2 ? null : discoverV2Knowledge(v2.retrieval, query, v2.currentGit, {
             scope: options.scope,
             limit: options.knowledgeLimit ?? 10,
             maxChars: options.maxChars ?? 4000,
         });
-    const applicableDeadends = query === null
-        ? emptyDeadends('')
-        : v2Deadends?.result ?? await discoverDeadends(projectRoot, query, {
+        const v2Deadends = query === null || !v2 ? null : discoverV2Deadends(v2.retrieval, query, v2.currentGit, {
             scope: options.scope,
             limit: options.deadendLimit ?? 10,
             maxChars: options.maxChars ?? 4000,
         });
-    const budget = { remaining: Math.max(0, options.maxChars ?? 4000) };
-    const resumeSummary = {
-        progressSummary: limited(loaded.resumeSummary.progressSummary, budget),
-        lastError: loaded.resumeSummary.lastError === null ? null : limited(loaded.resumeSummary.lastError, budget),
-        completed: limitedList(loaded.resumeSummary.completed, budget),
-        pendingTasks: limitedList(loaded.resumeSummary.pendingTasks, budget),
-        decisions: limitedList(loaded.resumeSummary.decisions, budget),
-        risks: limitedList(loaded.resumeSummary.risks, budget),
-        relatedFiles: limitedList(loaded.resumeSummary.relatedFiles, budget),
-        branchOrCommitDrift: loaded.resumeSummary.branchOrCommitDrift,
-    };
-    const resumeTruncated = textLength(resumeSummary.progressSummary) < textLength(loaded.resumeSummary.progressSummary)
-        || textLength(resumeSummary.lastError) < textLength(loaded.resumeSummary.lastError)
-        || textLength(resumeSummary.completed) < textLength(loaded.resumeSummary.completed)
-        || textLength(resumeSummary.pendingTasks) < textLength(loaded.resumeSummary.pendingTasks)
-        || textLength(resumeSummary.decisions) < textLength(loaded.resumeSummary.decisions)
-        || textLength(resumeSummary.risks) < textLength(loaded.resumeSummary.risks)
-        || textLength(resumeSummary.relatedFiles) < textLength(loaded.resumeSummary.relatedFiles);
-    const limitedKnowledgeResult = limitKnowledge(applicableKnowledge, budget);
-    const limitedDeadendResult = limitDeadends(applicableDeadends, budget);
-    const limitedNotesResult = limitNotes(notes, budget);
-    return {
-        status: 'ready',
-        projectRoot,
-        query,
-        context: {
-            id: loaded.context.id,
-            title: loaded.context.title,
-            status: loaded.context.status,
-            branch: loaded.context.branch,
-            commit: loaded.context.commit,
-            updatedAt: loaded.context.updatedAt,
-        },
-        snapshot: {
-            snapshotId: loaded.snapshot.snapshotId,
-            mode: loaded.snapshot.mode,
-            createdAt: loaded.snapshot.createdAt,
-            branch: loaded.snapshot.branch,
-            commit: loaded.snapshot.commit,
-        },
-        resumeSummary,
-        knowledge: limitedKnowledgeResult.result,
-        deadends: limitedDeadendResult.result,
-        notes: limitedNotesResult.notes,
-        truncated: resumeTruncated || limitedKnowledgeResult.truncated || limitedDeadendResult.truncated || limitedNotesResult.truncated,
-        explanation: {
-            mode: v2 ? 'v2' : 'v1-fallback',
-            selection: v2?.selection ?? 'v1',
-            retrieval: {
-                knowledge: v2Knowledge?.exclusions ?? {},
-                deadends: v2Deadends?.exclusions ?? {},
+        const applicableKnowledge = query === null
+            ? emptyKnowledge('')
+            : v2Knowledge?.result ?? await discoverKnowledge(projectRoot, query, {
+                scope: options.scope,
+                limit: options.knowledgeLimit ?? 10,
+                maxChars: options.maxChars ?? 4000,
+            });
+        const applicableDeadends = query === null
+            ? emptyDeadends('')
+            : v2Deadends?.result ?? await discoverDeadends(projectRoot, query, {
+                scope: options.scope,
+                limit: options.deadendLimit ?? 10,
+                maxChars: options.maxChars ?? 4000,
+            });
+        const budget = { remaining: Math.max(0, options.maxChars ?? 4000) };
+        const resumeSummary = {
+            progressSummary: limited(loaded.resumeSummary.progressSummary, budget),
+            lastError: loaded.resumeSummary.lastError === null ? null : limited(loaded.resumeSummary.lastError, budget),
+            completed: limitedList(loaded.resumeSummary.completed, budget),
+            pendingTasks: limitedList(loaded.resumeSummary.pendingTasks, budget),
+            decisions: limitedList(loaded.resumeSummary.decisions, budget),
+            risks: limitedList(loaded.resumeSummary.risks, budget),
+            relatedFiles: limitedList(loaded.resumeSummary.relatedFiles, budget),
+            branchOrCommitDrift: loaded.resumeSummary.branchOrCommitDrift,
+        };
+        const resumeTruncated = textLength(resumeSummary.progressSummary) < textLength(loaded.resumeSummary.progressSummary)
+            || textLength(resumeSummary.lastError) < textLength(loaded.resumeSummary.lastError)
+            || textLength(resumeSummary.completed) < textLength(loaded.resumeSummary.completed)
+            || textLength(resumeSummary.pendingTasks) < textLength(loaded.resumeSummary.pendingTasks)
+            || textLength(resumeSummary.decisions) < textLength(loaded.resumeSummary.decisions)
+            || textLength(resumeSummary.risks) < textLength(loaded.resumeSummary.risks)
+            || textLength(resumeSummary.relatedFiles) < textLength(loaded.resumeSummary.relatedFiles);
+        const limitedKnowledgeResult = limitKnowledge(applicableKnowledge, budget);
+        const limitedDeadendResult = limitDeadends(applicableDeadends, budget);
+        const limitedNotesResult = limitNotes(notes, budget);
+        return {
+            status: 'ready',
+            projectRoot,
+            query,
+            context: {
+                id: loaded.context.id,
+                title: loaded.context.title,
+                status: loaded.context.status,
+                branch: loaded.context.branch,
+                commit: loaded.context.commit,
+                updatedAt: loaded.context.updatedAt,
+            },
+            snapshot: {
+                snapshotId: loaded.snapshot.snapshotId,
+                mode: loaded.snapshot.mode,
+                createdAt: loaded.snapshot.createdAt,
+                branch: loaded.snapshot.branch,
+                commit: loaded.snapshot.commit,
             },
-            truncation: {
-                summary: resumeTruncated,
-                knowledge: limitedKnowledgeResult.truncated,
-                deadends: limitedDeadendResult.truncated,
-                notes: limitedNotesResult.truncated,
+            resumeSummary,
+            knowledge: limitedKnowledgeResult.result,
+            deadends: limitedDeadendResult.result,
+            notes: limitedNotesResult.notes,
+            truncated: resumeTruncated || limitedKnowledgeResult.truncated || limitedDeadendResult.truncated || limitedNotesResult.truncated,
+            explanation: {
+                mode: v2 ? 'v2' : 'v1-fallback',
+                selection: v2?.selection ?? 'v1',
+                retrieval: {
+                    knowledge: v2Knowledge?.exclusions ?? {},
+                    deadends: v2Deadends?.exclusions ?? {},
+                },
+                truncation: {
+                    summary: resumeTruncated,
+                    knowledge: limitedKnowledgeResult.truncated,
+                    deadends: limitedDeadendResult.truncated,
+                    notes: limitedNotesResult.truncated,
+                },
             },
-        },
+        };
     };
+    return interfaceName === null
+        ? action()
+        : withUsageTelemetry(startPath, 'orient', 'agent', options, action, interfaceName);
+}
+export async function contextUsageReport(startPath, options = {}) {
+    return buildUsageReport(startPath, options);
 }
 export async function recordContextUse(startPath, input) {
     return recordUse(startPath, input);

package/dist/src/agent/index.d.ts

@@ -1,6 +1,7 @@
 export * from './api.js';
 export type { ContextOrientContext, ContextUseInput, ContextOrientExplanation, ContextOrientNoContextResult, ContextOrientOptions, ContextOrientReadyResult, ContextOrientResult, ContextOrientSnapshot, } from './types.js';
 export type { AgentLoadOptions, AgentLoadResult, AgentSaveResult, ContextSearchHit, ContextSearchOptions, ContextSearchResult, } from '../runtime/types.js';
+export { contextCompile } from './api.js';
 export { compileContext } from '../compiler/compile.js';
 export { canonicalJson, contentHash, estimateTokens, rebuildManifestHash, validateManifestIdentity } from '../compiler/identity.js';
 export type { ContextActivityRecord, ContextAnchor, ContextBudget, ContextBudgetReport, ContextCandidate, ContextCandidateSection, ContextCompileOptions, ContextExpandInput, ContextExpandLevel, ContextExpandResult, ContextExclusion, ContextExclusionReason, ContextIntent, ContextIntentSignal, ContextLevel, ContextManifest, ContextProvenance, ContextScenario, ContextSourceDescriptor, ContextTruncation, } from '../compiler/types.js';

package/dist/src/agent/index.js

@@ -1,3 +1,4 @@
 export * from './api.js';
+export { contextCompile } from './api.js';
 export { compileContext } from '../compiler/compile.js';
 export { canonicalJson, contentHash, estimateTokens, rebuildManifestHash, validateManifestIdentity } from '../compiler/identity.js';

package/dist/src/cli/main.js

@@ -1,8 +1,7 @@
 #!/usr/bin/env node
-import { checkpoint, resume } from '../runtime/runtime.js';
-import { contextOrient } from '../agent/api.js';
-import { compileContext } from '../compiler/compile.js';
-import { contextExpand } from '../agent/api.js';
+import { checkpoint } from '../runtime/runtime.js';
+import { contextCompile, contextExpand, contextOrient, contextUsageReport, loadContext } from '../agent/api.js';
+import { formatUsageReport } from '../cognition/usage-report.js';
 import { importV1, verifyV1Import } from '../cognition/migration-v1.js';
 import { recordUse } from '../cognition/feedback.js';
 import { verifyJournal } from '../cognition/journal.js';
@@ -82,6 +81,34 @@ Initialize the local .context runtime layout. Re-running init is safe.
 
 Options:
   --path <path>  Project path`,
+    usage: `usage: ctx usage report [options]
+
+Show read-only context asset, reuse, token investment, and operation metrics.
+
+Options:
+  --path <path>                  Project path
+  --since <ISO>                  Window start
+  --until <ISO>                  Window end
+  --days <number>                Rolling window length (default: 30)
+  --month <YYYY-MM>              Calendar month window
+  --granularity <value>          day|week|month
+  --format <value>               json|ascii (default: json)
+  --baseline-tokens <number>    Explicit comparison token count
+  --baseline-source <value>      manual|recorded-control`,
+    'usage report': `usage: ctx usage report [options]
+
+Show read-only context asset, reuse, token investment, and operation metrics.
+
+Options:
+  --path <path>                  Project path
+  --since <ISO>                  Window start
+  --until <ISO>                  Window end
+  --days <number>                Rolling window length (default: 30)
+  --month <YYYY-MM>              Calendar month window
+  --granularity <value>          day|week|month
+  --format <value>               json|ascii (default: json)
+  --baseline-tokens <number>    Explicit comparison token count
+  --baseline-source <value>      manual|recorded-control`,
     checkpoint: `usage: ctx checkpoint [options]
 
 Save structured work state as a baseline or incremental snapshot.
@@ -161,7 +188,7 @@ Start an MCP stdio server for Agent integrations.
 Run "ctx agent serve --help" for details.`,
     'agent serve': `usage: ctx agent serve
 
-Start an MCP stdio server exposing context_orient, context_expand, context_compile, context_resume, context_note_list, context_note_add, and context_checkpoint tools.
+Start an MCP stdio server exposing context_orient, context_expand, context_compile, context_resume, context_note_list, context_note_add, context_usage_report, and context_checkpoint tools.
 
 The server owns standard input/output; do not use it interactively.`,
     hook: `usage: ctx hook claude-code session-start|user-prompt
@@ -363,7 +390,7 @@ Stop the local runtime through authenticated loopback IPC.`,
 Internal runtime daemon entry point.`,
 };
 function usage() {
-    return `usage: ctx init|checkpoint|resume|orient|compile|expand|agent|hook|integrate|status|doctor|learn|knowledge|deadend|deadends|note|activity|migrate|runtime|filesystem|feedback|journal [options]
+    return `usage: ctx init|checkpoint|resume|orient|compile|expand|usage|agent|hook|integrate|status|doctor|learn|knowledge|deadend|deadends|note|activity|migrate|runtime|filesystem|feedback|journal [options]
 
 Run \"ctx <command> --help\" for command details.`;
 }
@@ -392,7 +419,7 @@ function printHelp(args) {
         || (command === 'note' && ['add', 'list'].includes(args[1]))
         || (command === 'migrate' && ['v1', 'verify'].includes(args[1]))
         || (command === 'runtime' && ['enable', 'disable', 'start', 'stop', 'status', 'serve'].includes(args[1]))
-        || (command === 'filesystem' && ['enable', 'disable', 'status'].includes(args[1]));
+        || (command === 'usage' && args[1] === 'report');
     const key = nested ? `${command} ${args[1]}` : command;
     const nestedKey = key === 'integrate claude' && (args[2] === 'inspect' || args[2] === 'install') ? `${key} ${args[2]}` : key;
     const help = HELP[nestedKey];
@@ -450,7 +477,7 @@ async function run(args) {
         case 'resume':
             validateOptions(args.slice(1), ['--path', '--context', '--max-chars'], ['--path', '--context', '--max-chars']);
             validatePositionals(positionals(args.slice(1), ['--path', '--context', '--max-chars']), 0, HELP.resume);
-            print(await resume(target, option(args, '--context'), numericOption(args, '--max-chars', 4000)));
+            print(await loadContext(target, { contextId: option(args, '--context'), maxChars: numericOption(args, '--max-chars', 4000) }, 'cli'));
             return;
         case 'orient': {
             const valueOptions = ['--path', '--context', '--scope', '--max-chars', '--knowledge-limit', '--deadend-limit', '--note-limit'];
@@ -466,7 +493,7 @@ async function run(args) {
                 knowledgeLimit: numericOption(args, '--knowledge-limit', 10),
                 deadendLimit: numericOption(args, '--deadend-limit', 10),
                 noteLimit: numericOption(args, '--note-limit', 20),
-            }));
+            }, 'cli'));
             return;
         }
         case 'compile': {
@@ -474,7 +501,7 @@ async function run(args) {
             validateOptions(args.slice(1), valueOptions, valueOptions);
             const query = positionals(args.slice(1), valueOptions);
             validatePositionals(query, 1, HELP.compile);
-            print(await compileContext(target, {
+            print(await contextCompile(target, {
                 contextId: option(args, '--context'),
                 query: query[0],
                 scenario: enumOption(args, '--scenario', ['resume', 'implementation', 'debugging', 'verification', 'handoff', 'exploration', 'unknown']),
@@ -485,7 +512,7 @@ async function run(args) {
                 deadendLimit: numericOption(args, '--deadend-limit', 10),
                 noteLimit: numericOption(args, '--note-limit', 20),
                 activityLimit: numericOption(args, '--activity-limit', 20),
-            }));
+            }, 'cli'));
             return;
         }
         case 'expand': {
@@ -521,6 +548,27 @@ async function run(args) {
             }));
             return;
         }
+        case 'usage': {
+            if (args[1] !== 'report')
+                throw new Error(HELP.usage);
+            const valueOptions = ['--path', '--since', '--until', '--days', '--month', '--granularity', '--format', '--baseline-tokens', '--baseline-source'];
+            validateOptions(args.slice(2), valueOptions, valueOptions);
+            validatePositionals(positionals(args.slice(2), valueOptions), 0, HELP['usage report']);
+            const report = await contextUsageReport(target, {
+                since: option(args, '--since'),
+                until: option(args, '--until'),
+                days: option(args, '--days') === undefined ? undefined : numericOption(args, '--days', 30),
+                month: option(args, '--month'),
+                granularity: enumOption(args, '--granularity', ['day', 'week', 'month']),
+                baselineTokens: option(args, '--baseline-tokens') === undefined ? undefined : numericOption(args, '--baseline-tokens', 0),
+                baselineSource: enumOption(args, '--baseline-source', ['manual', 'recorded-control']),
+            });
+            if (enumOption(args, '--format', ['json', 'ascii']) === 'ascii')
+                process.stdout.write(formatUsageReport(report));
+            else
+                print(report);
+            return;
+        }
         case 'agent':
             if (args[1] !== 'serve')
                 throw new Error(HELP.agent);

package/dist/src/cognition/journal.js

@@ -11,9 +11,10 @@ const eventTypes = new Set([
     'context.checkpoint.imported', 'context.state.recorded', 'note.recorded', 'note.resolved', 'note.absorbed',
     'knowledge.proposed', 'knowledge.verified', 'knowledge.deprecated', 'knowledge.rejected',
     'deadend.proposed', 'deadend.verified', 'deadend.obsoleted', 'deadend.rejected', 'record.used',
+    'usage.operation.completed',
     'projection.advanced', 'projection.failed',
 ]);
-const sourceKinds = new Set(['cli', 'claude-hook', 'mcp', 'git-observer', 'fs-observer', 'migration']);
+const sourceKinds = new Set(['cli', 'claude-hook', 'mcp', 'agent', 'git-observer', 'fs-observer', 'migration']);
 const segmentName = '00000001.ndjson';
 function canonical(value) {
     if (value === null || typeof value !== 'object')
@@ -65,6 +66,17 @@ function validatePayloadBoundary(input) {
         if (!isRecord(record) || typeof record.message !== 'string' || record.message.trim().length === 0)
             throw new Error('note message must not be empty');
     }
+    if (input.type === 'usage.operation.completed') {
+        const requiredNumbers = ['durationMs', 'inputChars', 'outputChars', 'inputBytes', 'outputBytes', 'estimatedInputTokens', 'estimatedOutputTokens'];
+        if (payload.operation !== 'orient' && payload.operation !== 'compile' && payload.operation !== 'expand' && payload.operation !== 'resume')
+            throw new Error('invalid usage operation');
+        if (payload.interface !== 'cli' && payload.interface !== 'mcp' && payload.interface !== 'agent' && payload.interface !== 'hook')
+            throw new Error('invalid usage interface');
+        if (typeof payload.success !== 'boolean' || payload.estimatedMethod !== 'chars-div-four' || requiredNumbers.some((key) => typeof payload[key] !== 'number' || !Number.isFinite(payload[key]) || payload[key] < 0))
+            throw new Error('invalid usage telemetry payload');
+        if (!payload.success && typeof payload.errorClass !== 'string')
+            throw new Error('usage errors require an error class');
+    }
     if (input.type === 'workspace.paths.changed') {
         const changes = payload.changes;
         if (!Array.isArray(changes) || changes.length === 0)

package/dist/src/cognition/types.d.ts

@@ -1,6 +1,6 @@
 export declare const COGNITION_LAYOUT_VERSION: "event-journal-v2";
-export type CognitionEventSource = 'cli' | 'claude-hook' | 'mcp' | 'git-observer' | 'fs-observer' | 'migration';
-export type CognitionEventType = 'runtime.enabled' | 'runtime.started' | 'runtime.stopped' | 'host.session.started' | 'host.prompt.submitted' | 'git.state.observed' | 'git.branch.changed' | 'git.head.changed' | 'workspace.paths.changed' | 'context.checkpoint.imported' | 'context.state.recorded' | 'note.recorded' | 'note.resolved' | 'note.absorbed' | 'knowledge.proposed' | 'knowledge.verified' | 'knowledge.deprecated' | 'knowledge.rejected' | 'deadend.proposed' | 'deadend.verified' | 'deadend.obsoleted' | 'deadend.rejected' | 'record.used' | 'projection.advanced' | 'projection.failed';
+export type CognitionEventSource = 'cli' | 'claude-hook' | 'mcp' | 'agent' | 'git-observer' | 'fs-observer' | 'migration';
+export type CognitionEventType = 'runtime.enabled' | 'runtime.started' | 'runtime.stopped' | 'host.session.started' | 'host.prompt.submitted' | 'git.state.observed' | 'git.branch.changed' | 'git.head.changed' | 'workspace.paths.changed' | 'context.checkpoint.imported' | 'context.state.recorded' | 'note.recorded' | 'note.resolved' | 'note.absorbed' | 'knowledge.proposed' | 'knowledge.verified' | 'knowledge.deprecated' | 'knowledge.rejected' | 'deadend.proposed' | 'deadend.verified' | 'deadend.obsoleted' | 'deadend.rejected' | 'record.used' | 'usage.operation.completed' | 'projection.advanced' | 'projection.failed';
 export interface CognitionGitAnchor {
     worktreeId: string | null;
     branch: string | null;
@@ -67,6 +67,20 @@ export interface CognitionUseFeedback {
     entityId: string;
     outcome: 'used';
 }
+export interface UsageOperationCompletedPayload {
+    operation: 'orient' | 'compile' | 'expand' | 'resume';
+    interface: 'cli' | 'mcp' | 'agent' | 'hook';
+    success: boolean;
+    durationMs: number;
+    inputChars: number;
+    outputChars: number;
+    inputBytes: number;
+    outputBytes: number;
+    estimatedInputTokens: number;
+    estimatedOutputTokens: number;
+    estimatedMethod: 'chars-div-four';
+    errorClass?: string;
+}
 export interface CognitionRetrievalEntry {
     entity: 'knowledge' | 'deadend';
     entityId: string;

package/dist/src/cognition/usage-report.d.ts

@@ -0,0 +1,40 @@
+export type UsageReportFormat = 'json' | 'ascii';
+export type UsageGranularity = 'day' | 'week' | 'month';
+export interface UsageReportOptions {
+    since?: string;
+    until?: string;
+    days?: number;
+    month?: string;
+    granularity?: UsageGranularity;
+    baselineTokens?: number;
+    baselineSource?: 'manual' | 'recorded-control';
+}
+export interface UsageMetric<T> {
+    value: T | null;
+    quality: 'measured' | 'estimated' | 'derived' | 'unavailable';
+    unit: string;
+    method?: string;
+}
+interface Window {
+    from: string;
+    to: string;
+    kind: 'rolling' | 'calendar-month' | 'explicit';
+    granularity: UsageGranularity;
+}
+export interface UsageReport {
+    schemaVersion: 1;
+    generatedAt: string;
+    projectRoot: string;
+    window: Window;
+    dataQuality: Record<string, unknown>;
+    assets: Record<string, unknown>;
+    reuse: Record<string, unknown>;
+    investment: Record<string, unknown>;
+    payback: Record<string, unknown>;
+    operations: Record<string, unknown>;
+    trends: Array<Record<string, unknown>>;
+    warnings: string[];
+}
+export declare function buildUsageReport(startPath: string | undefined, options?: UsageReportOptions): Promise<UsageReport>;
+export declare function formatUsageReport(report: Record<string, any>): string;
+export {};

package/dist/src/cognition/usage-report.js

@@ -0,0 +1,232 @@
+import { readdir } from 'node:fs/promises';
+import { resolveProjectRoot } from '../project/project-resolver.js';
+import { readJson, isRecord } from '../storage/json-store.js';
+import { contextsRoot, contextMetadataPath, snapshotsDirectory } from '../storage/layout.js';
+import { readJournal } from './journal.js';
+import { listDeadends, listKnowledge } from '../runtime/knowledge.js';
+import { listNotes } from '../runtime/notes.js';
+function metric(value, quality, unit, method) {
+    return { value, quality, unit, ...(method ? { method } : {}) };
+}
+function iso(value) {
+    const time = Date.parse(value);
+    if (!Number.isFinite(time))
+        throw new Error(`invalid ISO date: ${value}`);
+    return new Date(time).toISOString();
+}
+function windowOf(options, now = new Date()) {
+    if (options.month && !/^\d{4}-\d{2}$/.test(options.month))
+        throw new Error('--month must be YYYY-MM');
+    if (options.since && options.month)
+        throw new Error('--since and --month cannot be combined');
+    if (options.days !== undefined && (!Number.isInteger(options.days) || options.days < 0))
+        throw new Error('--days must be a non-negative integer');
+    const to = options.until ? iso(options.until) : now.toISOString();
+    const toMs = Date.parse(to);
+    if (options.month) {
+        const [year, month] = options.month.split('-').map(Number);
+        const from = new Date(Date.UTC(year, month - 1, 1));
+        const end = new Date(Date.UTC(year, month, 1));
+        if (month < 1 || month > 12 || end.getUTCMonth() !== month % 12)
+            throw new Error('--month must be a valid calendar month');
+        return { from: from.toISOString(), to: end.toISOString(), kind: 'calendar-month', granularity: options.granularity ?? 'week' };
+    }
+    const from = options.since ? iso(options.since) : new Date(toMs - (options.days ?? 30) * 86_400_000).toISOString();
+    if (Date.parse(from) > toMs)
+        throw new Error('--since must not be after --until');
+    return { from, to, kind: options.since || options.until ? 'explicit' : 'rolling', granularity: options.granularity ?? 'day' };
+}
+function inWindow(event, window) {
+    const time = Date.parse(event.occurredAt);
+    return time >= Date.parse(window.from) && time < Date.parse(window.to);
+}
+function dayStart(value, granularity) {
+    const date = new Date(value);
+    if (granularity === 'month')
+        return new Date(Date.UTC(date.getUTCFullYear(), date.getUTCMonth(), 1)).toISOString();
+    if (granularity === 'week') {
+        const day = date.getUTCDay();
+        return new Date(Date.UTC(date.getUTCFullYear(), date.getUTCMonth(), date.getUTCDate() - (day === 0 ? 6 : day - 1))).toISOString();
+    }
+    return new Date(Date.UTC(date.getUTCFullYear(), date.getUTCMonth(), date.getUTCDate())).toISOString();
+}
+async function contexts(projectRoot) {
+    let ids = [];
+    try {
+        ids = await readdir(contextsRoot(projectRoot));
+    }
+    catch {
+        return { items: [], snapshots: 0 };
+    }
+    const items = [];
+    let snapshots = 0;
+    for (const id of ids) {
+        try {
+            const item = await readJson(contextMetadataPath(projectRoot, id), (value) => isRecord(value) && value.schemaVersion === 1 && value.id === id);
+            items.push(item);
+            snapshots += (await readdir(snapshotsDirectory(projectRoot, id))).filter((file) => file.endsWith('.json')).length;
+        }
+        catch { /* invalid files are reported by doctor */ }
+    }
+    return { items, snapshots };
+}
+function usagePayload(event) {
+    if (event.type !== 'usage.operation.completed' || !isRecord(event.payload))
+        return null;
+    const payload = event.payload;
+    return (payload.operation === 'orient' || payload.operation === 'compile' || payload.operation === 'expand' || payload.operation === 'resume')
+        && (payload.interface === 'cli' || payload.interface === 'mcp' || payload.interface === 'agent' || payload.interface === 'hook')
+        && typeof payload.success === 'boolean'
+        && typeof payload.durationMs === 'number' && Number.isFinite(payload.durationMs) && payload.durationMs >= 0
+        && typeof payload.inputChars === 'number' && Number.isFinite(payload.inputChars) && payload.inputChars >= 0
+        && typeof payload.outputChars === 'number' && Number.isFinite(payload.outputChars) && payload.outputChars >= 0
+        && typeof payload.inputBytes === 'number' && Number.isFinite(payload.inputBytes) && payload.inputBytes >= 0
+        && typeof payload.outputBytes === 'number' && Number.isFinite(payload.outputBytes) && payload.outputBytes >= 0
+        && typeof payload.estimatedInputTokens === 'number' && Number.isFinite(payload.estimatedInputTokens) && payload.estimatedInputTokens >= 0
+        && typeof payload.estimatedOutputTokens === 'number' && Number.isFinite(payload.estimatedOutputTokens) && payload.estimatedOutputTokens >= 0
+        && payload.estimatedMethod === 'chars-div-four'
+        ? payload : null;
+}
+function percentile(values, fraction) {
+    if (values.length === 0)
+        return null;
+    const sorted = [...values].sort((a, b) => a - b);
+    return sorted[Math.min(sorted.length - 1, Math.ceil(sorted.length * fraction) - 1)];
+}
+function operationStats(events) {
+    const groups = new Map();
+    for (const event of events) {
+        const payload = usagePayload(event);
+        if (!payload)
+            continue;
+        const key = payload.operation;
+        groups.set(key, [...(groups.get(key) ?? []), payload]);
+    }
+    const byOperation = {};
+    for (const [operation, values] of groups) {
+        const durations = values.map((item) => item.durationMs);
+        byOperation[operation] = {
+            calls: values.length,
+            successes: values.filter((item) => item.success).length,
+            failures: values.filter((item) => !item.success).length,
+            successRate: values.filter((item) => item.success).length / values.length,
+            errorRate: values.filter((item) => !item.success).length / values.length,
+            durationMs: { average: durations.reduce((sum, value) => sum + value, 0) / values.length, p50: percentile(durations, 0.5), p95: percentile(durations, 0.95), max: Math.max(...durations) },
+            inputChars: values.reduce((sum, item) => sum + item.inputChars, 0),
+            outputChars: values.reduce((sum, item) => sum + item.outputChars, 0),
+            inputBytes: values.reduce((sum, item) => sum + item.inputBytes, 0),
+            outputBytes: values.reduce((sum, item) => sum + item.outputBytes, 0),
+            estimatedInputTokens: values.reduce((sum, item) => sum + item.estimatedInputTokens, 0),
+            estimatedOutputTokens: values.reduce((sum, item) => sum + item.estimatedOutputTokens, 0),
+        };
+    }
+    return byOperation;
+}
+export async function buildUsageReport(startPath, options = {}) {
+    const projectRoot = await resolveProjectRoot(startPath);
+    const window = windowOf(options);
+    let events = [];
+    let journalVerified = true;
+    try {
+        events = await readJournal(projectRoot);
+    }
+    catch (error) {
+        if (!(error instanceof Error && /ENOENT|manifest|not initialized/i.test(error.message)))
+            throw error;
+        journalVerified = false;
+    }
+    const scoped = events.filter((event) => inWindow(event, window));
+    const usageEvents = scoped.map((event) => ({ event, payload: usagePayload(event) })).filter((item) => item.payload !== null);
+    const knowledge = await listKnowledge(projectRoot, true);
+    const deadends = await listDeadends(projectRoot, true);
+    const notes = await listNotes(projectRoot, { limit: Number.MAX_SAFE_INTEGER, maxChars: 0 });
+    const contextData = await contexts(projectRoot);
+    const used = new Map();
+    for (const event of events.filter((item) => item.type === 'record.used')) {
+        const payload = event.payload;
+        if (typeof payload.entity === 'string' && typeof payload.entityId === 'string')
+            used.set(`${payload.entity}:${payload.entityId}`, (used.get(`${payload.entity}:${payload.entityId}`) ?? 0) + 1);
+    }
+    const verified = [...knowledge.filter((item) => item.status === 'verified').map((item) => `knowledge:${item.knowledgeId}`), ...deadends.filter((item) => item.status === 'verified').map((item) => `deadend:${item.deadendId}`)];
+    const usedVerified = verified.filter((key) => (used.get(key) ?? 0) > 0).length;
+    const recordUsed = scoped.filter((event) => event.type === 'record.used').length;
+    const lifecycle = (type) => scoped.filter((event) => event.type === type).length;
+    const buckets = new Map();
+    for (const event of scoped) {
+        const key = dayStart(event.occurredAt, window.granularity);
+        const bucket = buckets.get(key) ?? { operations: 0, usageOperations: 0, recordsUsed: 0, outputChars: 0, estimatedOutputTokens: 0, knowledgeCreated: 0, knowledgeVerified: 0, deadendsCreated: 0, deadendsVerified: 0 };
+        const payload = usagePayload(event);
+        if (payload) {
+            bucket.operations += 1;
+            bucket.usageOperations += 1;
+            bucket.outputChars += payload.outputChars;
+            bucket.estimatedOutputTokens += payload.estimatedOutputTokens;
+        }
+        if (event.type === 'record.used')
+            bucket.recordsUsed += 1;
+        if (event.type === 'knowledge.proposed')
+            bucket.knowledgeCreated += 1;
+        if (event.type === 'knowledge.verified')
+            bucket.knowledgeVerified += 1;
+        if (event.type === 'deadend.proposed')
+            bucket.deadendsCreated += 1;
+        if (event.type === 'deadend.verified')
+            bucket.deadendsVerified += 1;
+        buckets.set(key, bucket);
+    }
+    const ctxTokens = usageEvents.reduce((sum, item) => sum + item.payload.estimatedOutputTokens, 0);
+    const baseline = options.baselineTokens ?? null;
+    const savings = baseline === null ? null : baseline - ctxTokens;
+    const investment = metric(ctxTokens, 'estimated', 'tokens', 'chars-div-four');
+    const rawAssets = verified.length;
+    const usedCount = verified.reduce((sum, key) => sum + Math.min(used.get(key) ?? 0, 3), 0);
+    const trendEntries = [...buckets.entries()].sort(([a], [b]) => a.localeCompare(b));
+    let cumulativeInvestmentTokens = 0;
+    let cumulativeOutputChars = 0;
+    let paybackPeriodStart = null;
+    const trends = trendEntries.map(([periodStart, values]) => {
+        cumulativeInvestmentTokens += values.estimatedOutputTokens;
+        cumulativeOutputChars += values.outputChars;
+        const cumulativeSavings = baseline === null ? null : baseline - cumulativeInvestmentTokens;
+        if (paybackPeriodStart === null && cumulativeSavings !== null && cumulativeSavings >= cumulativeInvestmentTokens)
+            paybackPeriodStart = periodStart;
+        return {
+            periodStart,
+            ...values,
+            cumulativeOutputChars,
+            cumulativeEstimatedOutputTokens: cumulativeInvestmentTokens,
+            cumulativeEstimatedSavings: cumulativeSavings,
+        };
+    });
+    const paybackReached = paybackPeriodStart !== null;
+    const paybackPeriodDays = paybackPeriodStart === null ? null : Math.max(0, (Date.parse(paybackPeriodStart) - Date.parse(window.from)) / 86_400_000);
+    return {
+        schemaVersion: 1, generatedAt: new Date().toISOString(), projectRoot, window,
+        dataQuality: { journalVerified, journalEventCount: events.length, windowEventCount: scoped.length, usageEventCount: usageEvents.length, firstUsageAt: usageEvents[0]?.event.occurredAt ?? null, lastUsageAt: usageEvents.at(-1)?.event.occurredAt ?? null, measuredMetricCount: usageEvents.length * 7, estimatedMetricCount: usageEvents.length * 2 + (ctxTokens > 0 ? 1 : 0), unavailableMetricCount: 1 },
+        assets: {
+            knowledge: { total: knowledge.length, candidate: knowledge.filter((item) => item.status === 'candidate').length, verified: knowledge.filter((item) => item.status === 'verified').length, retired: knowledge.filter((item) => ['deprecated', 'rejected'].includes(item.status)).length, created: lifecycle('knowledge.proposed'), verifiedInWindow: lifecycle('knowledge.verified') },
+            deadends: { total: deadends.length, candidate: deadends.filter((item) => item.status === 'candidate').length, verified: deadends.filter((item) => item.status === 'verified').length, retired: deadends.filter((item) => ['obsolete', 'rejected'].includes(item.status)).length, created: lifecycle('deadend.proposed'), verifiedInWindow: lifecycle('deadend.verified') },
+            notes: { total: notes.length, createdInWindow: lifecycle('note.recorded') }, contexts: { total: contextData.items.length, active: contextData.items.filter((item) => ['active', 'stable'].includes(item.status)).length, snapshots: contextData.snapshots }, rawVerifiedAssetCount: rawAssets, effectiveAssetPoints: metric(rawAssets + usedCount * 0.25, 'derived', 'asset-points'), assumptions: { reuseBonusPerUse: 0.25, maxBonusUses: 3 },
+        },
+        reuse: { recordUsedInWindow: recordUsed, recordUsedTotal: events.filter((event) => event.type === 'record.used').length, usedVerifiedAssetCount: usedVerified, verifiedAssetReuseRate: metric(rawAssets === 0 ? null : usedVerified / rawAssets, 'derived', 'ratio') },
+        investment: { contextOutputTokens: investment, providerTokens: metric(null, 'unavailable', 'tokens') },
+        payback: {
+            baselineTokens: baseline,
+            baselineSource: options.baselineSource ?? null,
+            estimatedSavings: savings === null ? metric(null, 'unavailable', 'tokens') : metric(savings, 'estimated', 'tokens'),
+            estimatedROI: baseline === null || ctxTokens === 0 ? null : savings / ctxTokens,
+            status: baseline === null ? 'no_baseline' : paybackReached ? 'reached' : 'not_reached',
+            paybackAt: paybackPeriodStart,
+            paybackPeriodDays,
+        },
+        operations: { available: usageEvents.length > 0, byOperation: operationStats(scoped), reason: usageEvents.length > 0 ? null : 'operation output telemetry is not yet recorded' },
+        trends,
+        warnings: [...(!journalVerified ? ['v2 journal unavailable; lifecycle metrics may be incomplete'] : []), 'Provider token usage is unavailable', ...(usageEvents.length === 0 ? ['Token investment is unavailable until operation output telemetry is recorded'] : [])],
+    };
+}
+export function formatUsageReport(report) {
+    const assets = report.assets;
+    const payback = report.payback;
+    const lines = ['fluffy-context usage report', `Window: ${String(report.window.from).slice(0, 10)} to ${String(report.window.to).slice(0, 10)}`, '', 'ASSET VALUE', `  Verified knowledge       ${assets.knowledge.verified}`, `  Verified deadends        ${assets.deadends.verified}`, `  Used verified assets     ${report.reuse.usedVerifiedAssetCount}`, `  Asset points             ${assets.effectiveAssetPoints.value.toFixed(2)}  derived`, '', 'TOKEN INVESTMENT', `  Estimated tokens         ${report.investment.contextOutputTokens.value}  estimated`, '  Provider tokens          n/a  unavailable', '', 'RETURN', `  Baseline tokens          ${payback.baselineTokens ?? 'n/a'}`, `  Estimated savings        ${payback.estimatedSavings.value ?? 'n/a'}`, `  ROI                      ${payback.estimatedROI ?? 'n/a'}`, `  Payback                  ${payback.status}`, '', 'COMMAND OUTPUT TREND', `  Usage events             ${report.dataQuality.usageEventCount}`, '', 'DATA QUALITY', `  Journal verified         ${report.dataQuality.journalVerified ? 'yes' : 'no'}`, `  Window events            ${report.dataQuality.windowEventCount}`, `  Warnings                 ${report.warnings.length}`];
+    return `${lines.join('\n')}\n`;
+}

package/dist/src/cognition/usage.d.ts

@@ -0,0 +1,5 @@
+import type { CognitionEventSource, UsageOperationCompletedPayload } from './types.js';
+export type UsageOperation = UsageOperationCompletedPayload['operation'];
+export type UsageInterface = UsageOperationCompletedPayload['interface'];
+export declare function recordUsageOperation(startPath: string | undefined, operation: UsageOperation, source: CognitionEventSource, input: unknown, output: unknown, startedAt: number, success: boolean, error?: unknown, interfaceName?: UsageInterface): Promise<void>;
+export declare function withUsageTelemetry<T>(startPath: string | undefined, operation: UsageOperation, source: CognitionEventSource, input: unknown, action: () => Promise<T>, interfaceName?: UsageInterface): Promise<T>;

package/dist/src/cognition/usage.js

@@ -0,0 +1,48 @@
+import { appendEvent } from './journal.js';
+function errorClass(error) {
+    return error instanceof Error ? error.constructor.name : typeof error;
+}
+function interfaceFor(source) {
+    return source === 'mcp' ? 'mcp' : source === 'claude-hook' ? 'hook' : source === 'agent' ? 'agent' : 'cli';
+}
+export async function recordUsageOperation(startPath, operation, source, input, output, startedAt, success, error, interfaceName = interfaceFor(source)) {
+    const inputText = typeof input === 'string' ? input : JSON.stringify(input ?? null);
+    const outputText = typeof output === 'string' ? output : JSON.stringify(output ?? null);
+    const payload = {
+        operation,
+        interface: interfaceName,
+        success,
+        durationMs: Math.max(0, Date.now() - startedAt),
+        inputChars: inputText.length,
+        outputChars: outputText.length,
+        inputBytes: Buffer.byteLength(inputText),
+        outputBytes: Buffer.byteLength(outputText),
+        estimatedInputTokens: Math.ceil(inputText.length / 4),
+        estimatedOutputTokens: Math.ceil(outputText.length / 4),
+        estimatedMethod: 'chars-div-four',
+        ...(success ? {} : { errorClass: errorClass(error) }),
+    };
+    try {
+        await appendEvent(startPath, {
+            type: 'usage.operation.completed',
+            source: { kind: source },
+            idempotencyKey: `usage:${operation}:${source}:${startedAt}:${Date.now()}:${Math.random().toString(36).slice(2)}`,
+            payload,
+        });
+    }
+    catch {
+        // Observability must not affect the operation being observed.
+    }
+}
+export async function withUsageTelemetry(startPath, operation, source, input, action, interfaceName = interfaceFor(source)) {
+    const startedAt = Date.now();
+    try {
+        const result = await action();
+        await recordUsageOperation(startPath, operation, source, input, result, startedAt, true, undefined, interfaceName);
+        return result;
+    }
+    catch (error) {
+        await recordUsageOperation(startPath, operation, source, input, { error: errorClass(error) }, startedAt, false, error, interfaceName);
+        throw error;
+    }
+}

package/dist/src/compiler/compile.js

@@ -321,7 +321,7 @@ export async function compileContext(startPath, options = {}) {
     });
     return {
         schemaVersion: 1,
-        compilerVersion: '0.7.6',
+        compilerVersion: '0.7.7',
         rankingVersion: 'compiler-ranking-v2',
         status: orientation.status,
         projectRoot: sources.anchor.projectRoot,

package/dist/src/compiler/identity.js

@@ -16,7 +16,7 @@ export function estimateTokens(value) {
 export function rebuildManifestHash(manifest) {
     return contentHash({
         schemaVersion: 1,
-        compilerVersion: '0.7.6',
+        compilerVersion: '0.7.7',
         rankingVersion: 'compiler-ranking-v2',
         status: manifest.status,
         projectRoot: manifest.projectRoot,

package/dist/src/compiler/sources.js

@@ -93,7 +93,7 @@ export async function loadCompilerSources(startPath, options) {
         knowledgeLimit: options.knowledgeLimit ?? 10,
         deadendLimit: options.deadendLimit ?? 10,
         noteLimit: options.noteLimit ?? 20,
-    });
+    }, null);
     const projectRoot = orientation.projectRoot;
     const git = await readGitWorktreeState(projectRoot);
     let events = [];

package/dist/src/compiler/types.d.ts

@@ -201,7 +201,7 @@ export interface ContextExpandResult {
 }
 export interface ContextManifest {
     schemaVersion: 1;
-    compilerVersion: '0.7.6';
+    compilerVersion: '0.7.7';
     rankingVersion: 'compiler-ranking-v2';
     status: 'ready' | 'no_context';
     projectRoot: string;

package/dist/src/mcp/server.js

@@ -1,8 +1,7 @@
 import { McpServer } from '@modelcontextprotocol/server';
 import { z } from 'zod';
-import { compileContext } from '../compiler/compile.js';
 import { addNote, listNotes } from '../runtime/notes.js';
-import { contextExpand, contextOrient, loadContext, saveContext } from '../agent/api.js';
+import { contextCompile, contextExpand, contextOrient, contextUsageReport, loadContext, saveContext } from '../agent/api.js';
 import { ensureRuntimeForSession } from '../cognition/runtime.js';
 import { VERSION } from '../version.js';
 const orientInput = z.object({
@@ -84,6 +83,16 @@ const checkpointInput = z.object({
     risks: z.array(z.string()).optional(),
     relatedFiles: z.array(z.string()).optional(),
 });
+const usageReportInput = z.object({
+    path: z.string().optional(),
+    since: z.string().optional(),
+    until: z.string().optional(),
+    days: z.int().nonnegative().optional(),
+    month: z.string().optional(),
+    granularity: z.enum(['day', 'week', 'month']).optional(),
+    baselineTokens: z.number().nonnegative().optional(),
+    baselineSource: z.enum(['manual', 'recorded-control']).optional(),
+});
 function errorMessage(error) {
     return error instanceof Error ? error.message : String(error);
 }
@@ -108,7 +117,7 @@ export function createMcpServer() {
     }, async ({ path, ...options }) => {
         try {
             await ensureRuntimeForSession(path, { source: 'mcp', timeoutMs: 1_000 }).catch(() => undefined);
-            return successResponse(await contextOrient(path, options));
+            return successResponse(await contextOrient(path, options, 'mcp'));
         }
         catch (error) {
             return failureResponse('context_orient', error);
@@ -121,7 +130,7 @@ export function createMcpServer() {
     }, async ({ path, ...input }) => {
         try {
             await ensureRuntimeForSession(path, { source: 'mcp', timeoutMs: 1_000 }).catch(() => undefined);
-            return successResponse(await contextExpand(path, input));
+            return successResponse(await contextExpand(path, input, 'mcp'));
         }
         catch (error) {
             return failureResponse('context_expand', error);
@@ -134,7 +143,7 @@ export function createMcpServer() {
     }, async ({ path, ...options }) => {
         try {
             await ensureRuntimeForSession(path, { source: 'mcp', timeoutMs: 1_000 }).catch(() => undefined);
-            return successResponse(await compileContext(path, options));
+            return successResponse(await contextCompile(path, options, 'mcp'));
         }
         catch (error) {
             return failureResponse('context_compile', error);
@@ -147,7 +156,7 @@ export function createMcpServer() {
     }, async ({ path, ...options }) => {
         try {
             await ensureRuntimeForSession(path, { source: 'mcp', timeoutMs: 1_000 }).catch(() => undefined);
-            return successResponse(await loadContext(path, options));
+            return successResponse(await loadContext(path, options, 'mcp'));
         }
         catch (error) {
             return failureResponse('context_resume', error);
@@ -179,6 +188,18 @@ export function createMcpServer() {
             return failureResponse('context_note_add', error);
         }
     });
+    server.registerTool('context_usage_report', {
+        title: 'Context usage report',
+        description: 'Build a read-only report of context assets, explicit reuse, estimated token investment, and operation metrics.',
+        inputSchema: usageReportInput,
+    }, async ({ path, ...options }) => {
+        try {
+            return successResponse(await contextUsageReport(path, options));
+        }
+        catch (error) {
+            return failureResponse('context_usage_report', error);
+        }
+    });
     server.registerTool('context_checkpoint', {
         title: 'Checkpoint context',
         description: 'Explicitly save context progress and create a Snapshot when changes are present; runtime rate limits remain enforced.',

package/dist/src/version.d.ts

@@ -1 +1 @@
-export declare const VERSION = "0.7.6";
+export declare const VERSION = "0.7.7";

package/dist/src/version.js

@@ -1 +1 @@
-export const VERSION = '0.7.6';
+export const VERSION = '0.7.7';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fluffy-context",
-  "version": "0.7.6",
+  "version": "0.7.7",
   "description": "Local context management CLI and MCP tools for AI coding agents",
   "license": "MIT",
   "author": "FluffyChi-Xing",

package/skills/fluffy-context/SKILL.md

@@ -19,12 +19,16 @@ compatibility: 需要 Node.js >=20.19.0；Git 可选。CLI 通过 npm 全局安
 - 仅需要完整详情时再运行 `ctx resume --max-chars <预算>`；它会保留既有的 `lastUsedAt` 更新语义。
 - Agent 集成从 `fluffy-context` 或 `fluffy-context/agent` 导入 `contextOrient`、`compileContext`、`saveContext`、`loadContext` 和 `searchContext`，不应直接读写 `.context` 或导入内部 `dist/...` 路径。
 - `ctx compile` 的 `activity` section 只表示 Runtime 观察到的近期文件 metadata 变化；它不代表文件被读取或理解，也不替代 checkpoint、Note 或已验证 Knowledge。
-- 0.7.6 的 Compiler Manifest 提供稳定 `identity.manifestHash`、候选 `itemHash`、`tokenEstimate` 和 `level` 契约；默认输出 `summary` 层。
+- 0.7.7 的 Compiler Manifest 提供稳定 `identity.manifestHash`、候选 `itemHash`、`tokenEstimate` 和 `level` 契约；默认输出 `summary` 层。
 - 只对 selected candidate 使用 `ctx expand --manifest-hash ... --candidate-id ... --level structured|evidence`。必须带上原始 compile 参数和相同的 compile budget；Manifest 过期时应重新 compile，不要绕过 hash 校验。
 - `expand` 是无状态、只读的渐进式展开：`complete` 才提供完整 `content`，`partial` 提供有界 `text` 且 `content` 为 null。它不写入 Context/journal、不记录 feedback、不读取项目文件正文、diff、命令输出或敏感数据。Agent API 使用 `contextExpand`，MCP 使用 `context_expand`。
 - 新任务先发现已验证共识，再开始实现；候选项只在显式审查时使用。
 - 普通查询只使用已验证 Knowledge 和 Deadend；需要审查候选项时显式使用 `--all`。
 - CLI 业务命令的标准输出是 JSON；错误写入标准错误并返回非零退出码。解析输出时不要把 `--help` 的纯文本当作 JSON。
+- 每周或每月复盘时使用 `ctx usage report`，不要为每条 prompt 运行；它只读 journal 和 v1 数据，不创建事件或修改项目状态。
+- Report 中的 `chars / 4` 是明确标注的 estimated token，不是真实 Provider token；Provider token 和计费金额当前 unavailable。
+- 只有显式 `record.used` 才算 Knowledge/Deadend reuse；compile 命中或 orient 返回不等于复用。
+- 没有显式 baseline 时，report 不生成 savings、ROI 或 payback 数字；report 不能替代 `doctor`、`journal verify` 或人工治理。
 
 ## 快速工作流
 
@@ -46,6 +50,21 @@ ctx learn ... / ctx deadend ... → 显式 verify
 
 `ctx orient` 不带查询时也有效，用于恢复当前任务和 open Note。带查询时只发现已验证的 Knowledge 与 Deadend；不要以候选项驱动普通实现。
 
+### Usage report
+
+在阶段性复盘、周报或月报时运行只读观测报告：
+
+```bash
+ctx usage report --days 30
+ctx usage report --month 2026-08 --granularity week
+ctx usage report --since 2026-08-01T00:00:00.000Z --until 2026-09-01T00:00:00.000Z --baseline-tokens 12000 --baseline-source manual
+ctx usage report --format ascii
+```
+
+JSON 是默认输出；`--format ascii` 仅用于终端展示。报告分别统计 v1 文件资产和 v2 journal 事件，展示 Knowledge、Deadend、Note、Context、Snapshot、显式 reuse、操作趋势与 estimated token 投入。`record.used` 是唯一的 reuse 信号，候选项命中、compile 选择和普通检索都不算复用。
+
+`--baseline-tokens` 必须是显式对照输入。未提供 baseline 时 savings、ROI 和 payback 为 `null` 或 `no_baseline`；字符换算不代表 Provider 真实 token，也不提供默认单价。报告失败时应使用 `ctx doctor` 与 `ctx journal verify` 进一步诊断，而不是把 report 当作数据修复工具。
+
 ### 初始化
 
 ```bash
@@ -103,7 +122,7 @@ ctx resume --path path/to/project --max-chars 2000
 
 ## MCP 与 Claude Code 集成
 
-`ctx agent serve` 提供 MCP stdio server，注册以下工具：`context_orient`、`context_expand`、`context_compile`、`context_resume`、`context_note_list`、`context_note_add` 和 `context_checkpoint`。标准输入和输出都是 MCP 协议，不能输出提示、日志或交互文本；调用错误是单次工具错误，不应让 server 退出。
+`ctx agent serve` 提供 MCP stdio server，注册以下工具：`context_orient`、`context_expand`、`context_compile`、`context_resume`、`context_note_list`、`context_note_add`、`context_usage_report` 和 `context_checkpoint`。标准输入和输出都是 MCP 协议，不能输出提示、日志或交互文本；调用错误是单次工具错误，不应让 server 退出。
 
 读取工作流通常是 `context_orient → context_compile → context_expand`。`context_compile` 与 `context_expand` 继续保持有界、确定性和不读取文件正文的边界；`context_resume` 复用 `loadContext`，可能更新 `lastUsedAt`。`context_note_list` 是只读的，`context_note_add` 和 `context_checkpoint` 是显式写入操作，分别新增 Note 或保存 Snapshot；它们不会自动记录 feedback、Knowledge、Deadend 或重复 checkpoint。Knowledge/Deadend 的完整记录和治理仍使用 CLI/Agent API。
 
@@ -341,7 +360,8 @@ ctx learn "订单取消后不能再次进入支付中状态"
 [ ] .contextignored 排除敏感和越界路径
 [ ] Knowledge candidate → verified
 [ ] Deadend candidate → verified
-[ ] MCP context_orient/context_expand/context_compile/context_resume/context_note_list/context_note_add/context_checkpoint 可调用，且单次错误不会终止 server
+[ ] MCP context_orient/context_expand/context_compile/context_resume/context_note_list/context_note_add/context_usage_report/context_checkpoint 可调用，且单次错误不会终止 server
+[ ] ctx usage report 的 JSON/ASCII 输出、baseline 边界和只读性符合预期
 [ ] MCP 只读工具不写入 Context；Note add 和 checkpoint 仅在显式调用时写入
 [ ] Claude 集成预览不写文件，--apply 幂等且拒绝冲突
 [ ] Hook 失败时 fail open，且不会自动 checkpoint