copilot-session-usage 0.2.2__tar.gz → 0.3.0__tar.gz

{copilot_session_usage-0.2.2 → copilot_session_usage-0.3.0}/CHANGELOG.md

@@ -1,5 +1,9 @@
 ## Unreleased
 
+## v0.2.3 (2026-07-03)
+
+## v0.2.2 (2026-07-03)
+
 ### Feat
 
 - accurate AIC cost computation using nanoAiu and cache_write

{copilot_session_usage-0.2.2 → copilot_session_usage-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: copilot-session-usage
-Version: 0.2.2
+Version: 0.3.0
 Summary: Usage and cost analytics for GitHub Copilot and Copilot-CLI session logs
 Project-URL: Homepage, https://github.com/gsemet/copilot-session-usage
 Project-URL: Documentation, https://copilot-session-usage.readthedocs.io/en/stable/
@@ -27,7 +27,7 @@ Description-Content-Type: text/markdown
 
 Extract VS Code Copilot session cost KPIs (tokens, estimated USD, model, duration) from local debug logs.
 
-**Full documentation:** [copilot-session-usage.readthedocs.io](https://copilot-session-usage.readthedocs.io/)
+**Full documentation:** [copilot-session-usage.readthedocs.io](https://copilot-session-usage.readthedocs.io/en/stable/)
 
 ## Installation
 
@@ -58,6 +58,7 @@ copilot-session-usage batch 10
 - **Threshold-aware pricing** — long-context tier switching (e.g. GPT-5.4 > 272k tokens)
 - **Subagent cost attribution** — tracks `runSubagent` calls and their token usage
 - **Cross-platform** — macOS, Linux, Windows, WSL2
+- **Three output formats** — `json` (default), `table`, `detailed`
 - **Three detail levels** — `minimal`, `compact`, `full`
 - **JSON and table output** — machine-readable or human-friendly
 

{copilot_session_usage-0.2.2 → copilot_session_usage-0.3.0}/README.md

@@ -11,7 +11,7 @@
 
 Extract VS Code Copilot session cost KPIs (tokens, estimated USD, model, duration) from local debug logs.
 
-**Full documentation:** [copilot-session-usage.readthedocs.io](https://copilot-session-usage.readthedocs.io/)
+**Full documentation:** [copilot-session-usage.readthedocs.io](https://copilot-session-usage.readthedocs.io/en/stable/)
 
 ## Installation
 
@@ -42,6 +42,7 @@ copilot-session-usage batch 10
 - **Threshold-aware pricing** — long-context tier switching (e.g. GPT-5.4 > 272k tokens)
 - **Subagent cost attribution** — tracks `runSubagent` calls and their token usage
 - **Cross-platform** — macOS, Linux, Windows, WSL2
+- **Three output formats** — `json` (default), `table`, `detailed`
 - **Three detail levels** — `minimal`, `compact`, `full`
 - **JSON and table output** — machine-readable or human-friendly
 

{copilot_session_usage-0.2.2 → copilot_session_usage-0.3.0}/docs/source/conf.py

@@ -24,6 +24,11 @@ extensions = [
 myst_enable_extensions = ["colon_fence", "deflist"]
 
 html_theme = "furo"
+html_theme_options = {
+    "source_repository": "https://github.com/gsemet/copilot-session-usage",
+    "source_branch": "main",
+    "source_directory": "docs/source/",
+}
 html_title = f"copilot-session-usage {version}"
 html_static_path = ["_static"]
 html_css_files = ["custom.css"]

{copilot_session_usage-0.2.2 → copilot_session_usage-0.3.0}/docs/source/index.md

@@ -1,5 +1,7 @@
 # copilot-session-usage
 
+[![GitHub](https://img.shields.io/badge/GitHub-copilot--session--usage-181717?logo=github)](https://github.com/gsemet/copilot-session-usage)
+
 **copilot-session-usage** reads VS Code Copilot debug logs and tells you
 how much each AI coding session cost in USD.
 
@@ -11,6 +13,8 @@ prints a cost report in seconds.
 The most common use: after a heavy agentic session, run
 `copilot-session-usage latest` to see what it cost.
 
+Links to source code: [gsemet/copilot-session-usage](https://github.com/gsemet/copilot-session-usage)
+
 ::::{grid} 1 1 2 2
 :gutter: 3
 

{copilot_session_usage-0.2.2 → copilot_session_usage-0.3.0}/docs/source/tutorials/getting-started.md

@@ -11,7 +11,7 @@ output. It assumes you have installed `copilot-session-usage` — see
 Run this after any VS Code Copilot chat session:
 
 ```bash
-copilot-session-usage latest
+copilot-session-usage latest --format table
 ```
 
 Sample output:
@@ -41,19 +41,16 @@ Each field:
 
 ---
 
-## Switch detail levels
+## Details Tables
 
-`--detail` controls how much data is shown:
+`--format` controls the output type. Default is `json`:
 
 ```bash
 # Just cost and model names
-copilot-session-usage latest --detail minimal
+copilot-session-usage latest --format table
 
-# Default: summary + per-model breakdown
-copilot-session-usage latest --detail compact
-
-# Everything: per-model + subagent attribution
-copilot-session-usage latest --detail full
+# Default: summary + per-subagent breakdown
+copilot-session-usage latest --format detailed
 ```
 
 ---
@@ -76,10 +73,16 @@ copilot-session-usage latest --format json --output session.json
 
 ## List recent sessions
 
-See which sessions exist without computing costs:
+See which sessions exist without computing costs (limit set to 20 by default):
 
 ```bash
 copilot-session-usage list
+
+# Limit to 5 sessions
+copilot-session-usage list --limit 5
+
+# Since a date
+copilot-session-usage list --since 2026-07-01
 ```
 
 Output:
@@ -106,7 +109,14 @@ it lists them so you can pick the right UUID.
 ## Analyze a specific session by UUID
 
 ```bash
+# Default json output
 copilot-session-usage id f5cbde8a-ec40-466f-86e6-f95c343b6c58
+
+# Human readable summary
+copilot-session-usage id f5cbde8a-ec40-466f-86e6-f95c343b6c58 --format table
+
+# Human readable details with per-subagent breakdown
+copilot-session-usage id f5cbde8a-ec40-466f-86e6-f95c343b6c58 --format detailed
 ```
 
 ---
@@ -114,8 +124,11 @@ copilot-session-usage id f5cbde8a-ec40-466f-86e6-f95c343b6c58
 ## Analyze multiple sessions at once
 
 ```bash
-# Last 10 sessions
+# Last 10 sessions (json output)
 copilot-session-usage batch 10
+
+# Summary table for last 10 sessions
+copilot-session-usage batch 10 --format table
 ```
 
 Output includes a summary row with aggregate totals and a per-session table.

{copilot_session_usage-0.2.2 → copilot_session_usage-0.3.0}/justfile

@@ -100,8 +100,7 @@ knowledge-validate:
 
 # Lint (format) OKF knowledge frontmatter in-place
 knowledge-lint:
-    uv run -- okf-schema lint --path knowledge
-    uv run -- okf-schema index --path knowledge
+    uv run -- okfkb update knowledge
 
 # Check OKF knowledge frontmatter without modifying files
 knowledge-lint-check:

copilot_session_usage-0.3.0/knowledge/_schema/Concept.schema.yaml

@@ -0,0 +1,41 @@
+$schema: "http://json-schema.org/draft-07/schema#"
+title: Concept
+description: >-
+  A stable, well-understood idea that explains "what is this." Concepts are
+  the semantic building blocks of the knowledge base.
+
+  Use Concept when an observation or hypothesis has converged into a durable
+  explanation. Do NOT use Concept for raw observations (use Finding), system
+  composition (use Structure), or human-agreed standards (use Principle).
+
+  Mutable. Concepts are updated to reflect new understanding as Findings
+  accumulate. They are never deleted; if entirely invalidated, they are
+  marked with `status: deprecated` and linked to replacement Concepts.
+
+  Belongs to the Semantic layer. Promoted from confirmed Hypotheses or
+  converged Findings. Supports Structures and Principles.
+allOf:
+  - $ref: "Base.schema.yaml"
+  - type: object
+    properties:
+      type:
+        description: Document type — must be "Concept" for concept documents.
+        type: string
+        const: Concept
+      status:
+        description: Lifecycle state of the concept.
+        type: string
+        enum: [active, deprecated]
+      derived_from:
+        description: IDs of Findings or Hypotheses that support this Concept.
+        type: array
+        items: { type: string }
+      related_concepts:
+        description: IDs of other Concept documents that deepen or contrast this idea.
+        type: array
+        items: { type: string }
+      prerequisites:
+        description: Concepts a reader should understand before engaging with this one.
+        type: array
+        items: { type: string }
+    required: [type]

{copilot_session_usage-0.2.2 → copilot_session_usage-0.3.0}/knowledge/_schema/Experiment.schema.yaml

@@ -1,9 +1,20 @@
 $schema: "http://json-schema.org/draft-07/schema#"
 title: Experiment
 description: >-
-  A reusable, prepared procedure that can be executed one or two times to test a
-  hypothesis. Each execution produces one Finding. The Experiment is a template;
-  its recorded outcomes live as Finding documents.
+  A reusable, prepared procedure designed to test a Hypothesis and produce
+  empirical Findings. Each execution yields one or more Finding documents.
+
+  Use Experiment when you need a reproducible test procedure. Do NOT use
+  Experiment for ad-hoc observations (write a Finding directly) or for
+  operational workflows (use Playbook).
+
+  The Experiment template itself is mutable while in `proposed` or `active`
+  status. Once `retired` or `superseded`, it should not be modified.
+  Outcomes are recorded as separate Finding documents, not by editing the
+  Experiment.
+
+  Belongs to the Testing layer. Tests Hypotheses. Produces Findings. May be
+  superseded by improved experimental designs.
 allOf:
   - $ref: "Base.schema.yaml"
   - type: object

{copilot_session_usage-0.2.2 → copilot_session_usage-0.3.0}/knowledge/_schema/Finding.schema.yaml

@@ -1,10 +1,22 @@
 $schema: "http://json-schema.org/draft-07/schema#"
 title: Finding
 description: >-
-  An empirical, dated, falsifiable record of what an agent or human truthfully
-  observed and believed at a point in time. The body is immutable once written;
-  only lifecycle frontmatter (status, contradicted_by, superseded_by) may be
-  appended later.
+  A raw, dated, falsifiable observation recorded by an agent or human at a
+  specific point in time. Findings are the atomic unit of empirical knowledge.
+
+  Use Finding when you have observed something non-trivial during debugging,
+  investigation, or experimentation and want to preserve that observation for
+  future agents. Do NOT use Finding for stable truths (use Concept), procedures
+  (use Playbook), or human-agreed standards (use Principle).
+
+  The body and claim are immutable once written. To correct a Finding, write a
+  new Finding with `contradicts` or `supersedes` pointing to the old one. The
+  only permitted edits to an existing Finding are lifecycle frontmatter:
+  `status` (active, contradicted, superseded), `contradicted_by`, and
+  `superseded_by`, appended by review.
+
+  Belongs to the Storage layer. Findings are promoted into Concepts or
+  Structures when they converge and stabilize. They may also support Principles.
 allOf:
   - $ref: "Base.schema.yaml"
   - type: object

copilot_session_usage-0.3.0/knowledge/_schema/Hypothesis.schema.yaml

@@ -0,0 +1,45 @@
+$schema: "http://json-schema.org/draft-07/schema#"
+title: Hypothesis
+description: >-
+  A testable proposition or educated guess derived from observations, intended
+  to be validated or falsified through experimentation.
+
+  Use Hypothesis when you have an idea that needs testing before it can be
+  treated as stable knowledge. Do NOT use Hypothesis for already-confirmed
+  truths (use Concept or Structure) or for planned deliverables (use Outcome).
+
+  Mutable until tested. Once tested, its status becomes `confirmed` or
+  `falsified`. A confirmed Hypothesis is promoted to Concept or Structure
+  (human decision). A falsified Hypothesis remains in the knowledge base with
+  `status: falsified` to preserve the record of what was tried.
+
+  Belongs to the Testing layer. Derived from Findings or direct observation.
+  Promoted to Concept or Structure when confirmed. Produces Experiments.
+allOf:
+  - $ref: "Base.schema.yaml"
+  - type: object
+    properties:
+      type:
+        description: Document type — must be "Hypothesis".
+        type: string
+        const: Hypothesis
+      derived_from:
+        description: IDs of Findings or Concepts that motivated this hypothesis.
+        type: array
+        items: { type: string }
+      status:
+        description: Lifecycle state of the hypothesis.
+        type: string
+        enum: [proposed, under_test, confirmed, falsified]
+      confirmed_by:
+        description: IDs of Findings that confirm this hypothesis.
+        type: array
+        items: { type: string }
+      falsified_by:
+        description: IDs of Findings that falsify this hypothesis.
+        type: array
+        items: { type: string }
+      promoted_to:
+        description: ID of the Concept or Structure this hypothesis was promoted into.
+        type: string
+    required: [type, status]

copilot_session_usage-0.3.0/knowledge/_schema/Outcome.schema.yaml

@@ -0,0 +1,40 @@
+$schema: "http://json-schema.org/draft-07/schema#"
+title: Outcome
+description: >-
+  A planned deliverable, project, or artifact to be built from the knowledge
+  base — "what I want to build."
+
+  Use Outcome when defining a concrete goal, feature, or deliverable that
+  emerges from stable knowledge. Do NOT use Outcome for procedures (use
+  Playbook), observations (use Finding), or testable guesses (use Hypothesis).
+
+  Mutable. Tracks progress from `planned` → `in_progress` → `done` or
+  `cancelled`. May reference Playbooks as execution paths and Concepts/
+  Structures as foundational knowledge.
+
+  Belongs to the Planning layer. Derived from Concepts, Structures, and
+  Principles. References Playbooks for execution.
+allOf:
+  - $ref: "Base.schema.yaml"
+  - type: object
+    properties:
+      type:
+        description: Document type — must be "Outcome".
+        type: string
+        const: Outcome
+      status:
+        description: Progress state of the outcome.
+        type: string
+        enum: [planned, in_progress, done, cancelled]
+      deliverable:
+        description: Description of the concrete artifact or result to be produced.
+        type: string
+      derived_from:
+        description: IDs of Concepts, Structures, or Principles that motivate this outcome.
+        type: array
+        items: { type: string }
+      execution_playbooks:
+        description: IDs of Playbooks that describe how to achieve this outcome.
+        type: array
+        items: { type: string }
+    required: [type, status]

copilot_session_usage-0.3.0/knowledge/_schema/Playbook.schema.yaml

@@ -0,0 +1,41 @@
+$schema: "http://json-schema.org/draft-07/schema#"
+title: Playbook
+description: >-
+  A reproducible, step-by-step workflow or procedure that produces a specific
+  result given the current understanding of the system.
+
+  Use Playbook when documenting "how to do X" — deployment steps, debugging
+  procedures, setup guides. Do NOT use Playbook for one-off observations
+  (use Finding), system architecture (use Structure), or planned deliverables
+  (use Outcome).
+
+  Mutable while active. When a better workflow is found, the old Playbook is
+  marked `status: deprecated` or `superseded` with `superseded_by` pointing to
+  the replacement. Playbooks are experienced until proven false or obsolete.
+
+  Belongs to the Operational layer. References Concepts and Structures for
+  context. May be referenced by Outcomes as execution paths.
+allOf:
+  - $ref: "Base.schema.yaml"
+  - type: object
+    properties:
+      type:
+        description: Document type — must be "Playbook" for playbook documents.
+        type: string
+        const: Playbook
+      status:
+        description: Lifecycle state of the playbook.
+        type: string
+        enum: [active, deprecated, superseded]
+      superseded_by:
+        description: IDs of Playbooks that replace this one.
+        type: array
+        items: { type: string }
+      estimated_duration:
+        description: Approximate time to complete the playbook (e.g., "15 min", "2 h").
+        type: string
+      tools_required:
+        description: CLI tools, scripts, or external utilities the reader must have installed.
+        type: array
+        items: { type: string }
+    required: [type]

copilot_session_usage-0.3.0/knowledge/_schema/Principle.schema.yaml

@@ -0,0 +1,37 @@
+$schema: "http://json-schema.org/draft-07/schema#"
+title: Principle
+description: >-
+  A durable, normative statement agreed upon by humans — "we always…",
+  "never…", "must…". Principles include rules, conventions, and governance
+  directives.
+
+  Use Principle when establishing a team standard, coding convention, or
+  architectural rule that requires human agreement. Do NOT use Principle for
+  observations (use Finding), explanations (use Concept), or workflows
+  (use Playbook).
+
+  Stable. Changed only through explicit human review. Principles are supported
+  by Findings but are not dictated by them. Superseded Principles retain their
+  record with `superseded_by` linking to the replacement.
+
+  Belongs to the Governance layer. Supported by Findings. May reference
+  Concepts and Structures for context.
+allOf:
+  - $ref: "Base.schema.yaml"
+  - type: object
+    properties:
+      type:
+        description: Document type — must be "Principle".
+        type: string
+        const: Principle
+      rationale:
+        description: Why this principle exists and what it protects against.
+        type: string
+      authority:
+        description: Who agreed this principle (e.g. "team", "human-reviewed").
+        type: string
+      supported_by:
+        description: IDs of Findings that provide empirical support for this principle.
+        type: array
+        items: { type: string }
+    required: [type]

copilot_session_usage-0.3.0/knowledge/_schema/Reference.schema.yaml

@@ -0,0 +1,34 @@
+$schema: "http://json-schema.org/draft-07/schema#"
+title: Reference
+description: >-
+  An external source document — scientific papers, API specifications, lookup
+  tables, or authoritative references — mirrored or linked within the knowledge
+  base.
+
+  Use Reference when bringing external information into the knowledge base for
+  easy agent access. Do NOT use Reference for your own observations (use
+  Finding), interpretations (use Concept), or workflows (use Playbook). Personal
+  notes on a paper belong in a Finding or Concept, not in Reference.
+
+  Immutable. References mirror or link to external sources. If the upstream
+  changes, create a new Reference with updated `schema_version` rather than
+  editing the old one.
+
+  Belongs to the Lookup layer. Referenced by Concepts, Structures, Principles,
+  and Findings for authoritative backing.
+allOf:
+  - $ref: "Base.schema.yaml"
+  - type: object
+    properties:
+      type:
+        description: Document type — must be "Reference" for reference documents.
+        type: string
+        const: Reference
+      schema_version:
+        description: Version of the data schema or API documented here (e.g., "v2.1").
+        type: string
+      authoritative_source:
+        description: URL or identifier of the canonical upstream specification this reference mirrors.
+        type: string
+        format: uri
+    required: [type]

copilot_session_usage-0.3.0/knowledge/_schema/Structure.schema.yaml

@@ -0,0 +1,45 @@
+$schema: "http://json-schema.org/draft-07/schema#"
+title: Structure
+description: >-
+  A description of how an object, system, or artifact is composed and how its
+  parts relate — the "how it works" view.
+
+  Use Structure when documenting system architecture, component relationships,
+  or mechanical composition. Do NOT use Structure for abstract ideas (use
+  Concept), operational procedures (use Playbook), or human-agreed standards
+  (use Principle).
+
+  Mutable. Updated as the system evolves. Like Concepts, Structures are never
+  deleted; obsolete Structures are marked `status: deprecated` and linked to
+  replacements.
+
+  Belongs to the Semantic layer. Promoted from confirmed Hypotheses or
+  converged Findings. Cross-cuts multiple Concepts.
+allOf:
+  - $ref: "Base.schema.yaml"
+  - type: object
+    properties:
+      type:
+        description: Document type — must be "Structure".
+        type: string
+        const: Structure
+      status:
+        description: Lifecycle state of the structure.
+        type: string
+        enum: [active, deprecated]
+      derived_from:
+        description: IDs of Findings or Hypotheses that support this Structure.
+        type: array
+        items: { type: string }
+      subject:
+        description: The object or system whose structure is described.
+        type: string
+      parts:
+        description: The components, fields, or sub-parts that make up the subject.
+        type: array
+        items: { type: string }
+      related_concepts:
+        description: IDs of Concept documents that explain the ideas behind this structure.
+        type: array
+        items: { type: string }
+    required: [type]

{copilot_session_usage-0.2.2 → copilot_session_usage-0.3.0}/knowledge/concepts/index.md

@@ -1,6 +1,9 @@
 # Concept
 
-A core concept or explanatory document in the knowledge base.
+A stable, well-understood idea that explains "what is this." Concepts are the semantic building blocks of the knowledge base.
+Use Concept when an observation or hypothesis has converged into a durable explanation. Do NOT use Concept for raw observations (use Finding), system composition (use Structure), or human-agreed standards (use Principle).
+Mutable. Concepts are updated to reflect new understanding as Findings accumulate. They are never deleted; if entirely invalidated, they are marked with `status: deprecated` and linked to replacement Concepts.
+Belongs to the Semantic layer. Promoted from confirmed Hypotheses or converged Findings. Supports Structures and Principles.
 
 - [Copilot CLI Differences](copilot-cli.md) — How session cost tracking differs when using copilot-cli instead of the VS Code extension.  [Concept]
 - [Session Cost Analysis](session-cost-analysis.md) — Process of extracting token usage metrics from Copilot debug logs and estimating monetary cost based on per-model pricing.  [Concept]

copilot_session_usage-0.3.0/knowledge/experiments/index.md

@@ -0,0 +1,8 @@
+# Experiment
+
+A reusable, prepared procedure designed to test a Hypothesis and produce empirical Findings. Each execution yields one or more Finding documents.
+Use Experiment when you need a reproducible test procedure. Do NOT use Experiment for ad-hoc observations (write a Finding directly) or for operational workflows (use Playbook).
+The Experiment template itself is mutable while in `proposed` or `active` status. Once `retired` or `superseded`, it should not be modified. Outcomes are recorded as separate Finding documents, not by editing the Experiment.
+Belongs to the Testing layer. Tests Hypotheses. Produces Findings. May be superseded by improved experimental designs.
+
+- [Verify Subagent Cost Attribution](verify-subagent-cost-attribution.md) — Check that subagent token costs are attributed to their runSubagent call and not double-counted in the parent session total.  [Experiment]

copilot_session_usage-0.2.2/knowledge/findings/subagent-logs-use-runsubagent-prefix.md → copilot_session_usage-0.3.0/knowledge/findings/2026.07.02-00.00-subagent-logs-runsubagent-prefix.md

@@ -14,7 +14,8 @@ context: >-
   future extension versions, which may not remain true.
 status: active
 links: []
-backlinks: []
+backlinks: [structures/subagent-cost-tracking.md]
+okf_version: "0.1"
 ---
 
 # Subagent Logs Use runSubagent Prefix

copilot_session_usage-0.2.2/knowledge/findings/title-jsonl-not-counted-as-model-turn.md → copilot_session_usage-0.3.0/knowledge/findings/2026.07.02-22.00-title-generation-not-counted-as-model-turn.md

@@ -16,6 +16,7 @@ timestamp: 2026-07-02T22:00:00Z
 links: []
 backlinks: [structures/subagent-cost-tracking.md,
     structures/vscode-copilot-extension.md]
+okf_version: "0.1"
 ---
 
 # Finding: title-*.jsonl not counted as "Model Turn" by VS Code panel

copilot_session_usage-0.2.2/knowledge/findings/cache-write-cost-not-tracked.md → copilot_session_usage-0.3.0/knowledge/findings/2026.07.02-23.00-cache-write-approximation.md

@@ -15,6 +15,7 @@ context: >-
 timestamp: 2026-07-02T23:00:00Z
 links: []
 backlinks: [structures/cache-cost-approximation.md]
+okf_version: "0.1"
 ---
 
 # Finding: cache_write approximated via fresh_input — now implemented

copilot_session_usage-0.3.0/knowledge/findings/index.md

@@ -0,0 +1,10 @@
+# Finding
+
+A raw, dated, falsifiable observation recorded by an agent or human at a specific point in time. Findings are the atomic unit of empirical knowledge.
+Use Finding when you have observed something non-trivial during debugging, investigation, or experimentation and want to preserve that observation for future agents. Do NOT use Finding for stable truths (use Concept), procedures (use Playbook), or human-agreed standards (use Principle).
+The body and claim are immutable once written. To correct a Finding, write a new Finding with `contradicts` or `supersedes` pointing to the old one. The only permitted edits to an existing Finding are lifecycle frontmatter: `status` (active, contradicted, superseded), `contradicted_by`, and `superseded_by`, appended by review.
+Belongs to the Storage layer. Findings are promoted into Concepts or Structures when they converge and stabilize. They may also support Principles.
+
+- [cache_write approximated via fresh_input — matches AIC panel exactly](2026.07.02-23.00-cache-write-approximation.md) — VS Code JSONL logs and agent-traces.db both lack cache_creation token counts. Approximating cache_creation as fresh_input = inputTokens - cachedTokens and billing only the incremental delta (cache_write - input) / 1M produces an exact match to the VS Code AIC panel. Implemented in estimate_cost since v0.3.  [Finding]
+- [Subagent Logs Use runSubagent Prefix](2026.07.02-00.00-subagent-logs-runsubagent-prefix.md) — Subagent activity is recorded in separate JSONL files prefixed with "runSubagent-" inside the session debug-logs directory.  [Finding]
+- [title-*.jsonl adds 1 LLM call and its tokens to tool totals; VS Code panel excludes it](2026.07.02-22.00-title-generation-not-counted-as-model-turn.md) — The VS Code Agent Debug panel "Model Turns" counter excludes title-generation calls. copilot-session-usage counts them. The delta is exactly the title-*.jsonl file's token counts.  [Finding]

copilot_session_usage-0.3.0/knowledge/guides/index.md

@@ -0,0 +1,10 @@
+# Playbook
+
+A reproducible, step-by-step workflow or procedure that produces a specific result given the current understanding of the system.
+Use Playbook when documenting "how to do X" — deployment steps, debugging procedures, setup guides. Do NOT use Playbook for one-off observations (use Finding), system architecture (use Structure), or planned deliverables (use Outcome).
+Mutable while active. When a better workflow is found, the old Playbook is marked `status: deprecated` or `superseded` with `superseded_by` pointing to the replacement. Playbooks are experienced until proven false or obsolete.
+Belongs to the Operational layer. References Concepts and Structures for context. May be referenced by Outcomes as execution paths.
+
+- [Automation Scripts for Cost Extraction](automation-scripts.md) — Reference Python patterns for extracting and aggregating session costs from Copilot debug logs.  [Playbook]
+- [Cost Optimization Patterns](cost-optimization.md) — Common patterns that inflate session costs and strategies to reduce them.  [Playbook]
+- [WSL2 Setup Guide](wsl2-setup.md) — Configure copilot-session-usage when running VS Code on Windows with WSL2, including path resolution and troubleshooting.  [Playbook]

copilot_session_usage-0.3.0/knowledge/ideas/index.md

@@ -0,0 +1,8 @@
+# Concept
+
+A stable, well-understood idea that explains "what is this." Concepts are the semantic building blocks of the knowledge base.
+Use Concept when an observation or hypothesis has converged into a durable explanation. Do NOT use Concept for raw observations (use Finding), system composition (use Structure), or human-agreed standards (use Principle).
+Mutable. Concepts are updated to reflect new understanding as Findings accumulate. They are never deleted; if entirely invalidated, they are marked with `status: deprecated` and linked to replacement Concepts.
+Belongs to the Semantic layer. Promoted from confirmed Hypotheses or converged Findings. Supports Structures and Principles.
+
+- [Multi-Session Efficiency Analytics — Idea Specification](multi-session-efficiency-analytics.md) — Cross-session analytics that group related VS Code Copilot sessions into coding tasks, score subagent efficiency, and surface trends in cost, latency, and behavior over time.  [Concept]

copilot_session_usage-0.3.0/knowledge/index.md

@@ -0,0 +1,17 @@
+---
+okf_version: "0.1"
+links: []
+backlinks: []
+---
+
+# knowledge
+
+- [concepts](./concepts/) — A stable, well-understood idea that explains "what is this." Concepts are the semantic building blocks of the knowled...
+- [experiments](./experiments/) — A reusable, prepared procedure designed to test a Hypothesis and produce empirical Findings. Each execution yields on...
+- [findings](./findings/) — A raw, dated, falsifiable observation recorded by an agent or human at a specific point in time. Findings are the ato...
+- [guides](./guides/) — A reproducible, step-by-step workflow or procedure that produces a specific result given the current understanding of...
+- [ideas](./ideas/) — A stable, well-understood idea that explains "what is this." Concepts are the semantic building blocks of the knowled...
+- [principles](./principles/) — A durable, normative statement agreed upon by humans — "we always…", "never…", "must…". Principles include rules, con...
+- [reference](./reference/) — An external source document — scientific papers, API specifications, lookup tables, or authoritative references — mir...
+- [structures](./structures/) — A description of how an object, system, or artifact is composed and how its parts relate — the "how it works" view.
+U...

copilot_session_usage-0.3.0/knowledge/log.md

@@ -0,0 +1,3 @@
+# Update Log
+
+## 2026-07-06

copilot_session_usage-0.3.0/knowledge/principles/index.md

@@ -0,0 +1,8 @@
+# Principle
+
+A durable, normative statement agreed upon by humans — "we always…", "never…", "must…". Principles include rules, conventions, and governance directives.
+Use Principle when establishing a team standard, coding convention, or architectural rule that requires human agreement. Do NOT use Principle for observations (use Finding), explanations (use Concept), or workflows (use Playbook).
+Stable. Changed only through explicit human review. Principles are supported by Findings but are not dictated by them. Superseded Principles retain their record with `superseded_by` linking to the replacement.
+Belongs to the Governance layer. Supported by Findings. May reference Concepts and Structures for context.
+
+- [Findings Are Immutable](findings-are-immutable.md) — A recorded Finding's body is never reworded or deleted — only linked.  [Principle]