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

{copilot_session_usage-0.2.3 → 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.3 → copilot_session_usage-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: copilot-session-usage
-Version: 0.2.3
+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/
@@ -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.3 → copilot_session_usage-0.3.0}/README.md

@@ -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.3 → 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.3 → 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.3 → 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.3 → 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.3/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.3/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.3/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]

copilot_session_usage-0.3.0/knowledge/reference/index.md

@@ -0,0 +1,9 @@
+# Reference
+
+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.
+
+- [Debug Log JSONL Format](debug-log-format.md) — Structure of Copilot debug log events, with focus on fields relevant to cost extraction.  [Reference]
+- [Pricing Data Formats](pricing-formats.md) — Schema and format documentation for models-and-pricing.yml, custom-models-pricing.yml, and the internal pricing dict.  [Reference]

{copilot_session_usage-0.2.3 → copilot_session_usage-0.3.0}/knowledge/structures/cache-cost-approximation.md

@@ -7,8 +7,9 @@ tags: [cache-write, anthropic, approximation, cost-estimation, aic]
 timestamp: 2026-07-03T00:00:00Z
 related_concepts: [concepts/session-cost-analysis.md]
 links: [concepts/session-cost-analysis.md,
-    findings/cache-write-cost-not-tracked.md]
+    findings/2026.07.02-23.00-cache-write-approximation.md]
 backlinks: []
+okf_version: "0.1"
 ---
 
 # Cache Cost Approximation
@@ -63,7 +64,7 @@ Verified on session `438d24a8` (Claude Sonnet 4.6, 92 calls):
 | VS Code AIC panel (590.37 AIC ÷ 100) | **$5.9037** |
 
 Exact match. Supporting Finding:
-[`cache-write-cost-not-tracked`](../findings/cache-write-cost-not-tracked.md).
+[`2026.07.02-23.00-cache-write-approximation`](../findings/2026.07.02-23.00-cache-write-approximation.md).
 
 ## Accuracy Characteristics
 
@@ -82,5 +83,5 @@ retired.
 
 ## Related
 
-- [`findings/cache-write-cost-not-tracked.md`](../findings/cache-write-cost-not-tracked.md) — Supporting empirical evidence
+- [`findings/2026.07.02-23.00-cache-write-approximation.md`](../findings/2026.07.02-23.00-cache-write-approximation.md) — Supporting empirical evidence
 - [`concepts/session-cost-analysis.md`](../concepts/session-cost-analysis.md) — Cost analysis overview

{copilot_session_usage-0.2.3 → copilot_session_usage-0.3.0}/knowledge/structures/index.md

@@ -1,6 +1,9 @@
 # Structure
 
-A description of how an object, system, or artifact is composed and how its parts relate — the "how it works" view. Distinct from a Concept (an idea) and from a Playbook (a procedure to perform).
+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.
 
 - [Cache Cost Approximation](cache-cost-approximation.md) — How copilot-session-usage approximates Anthropic cache-write costs when VS Code debug logs do not expose cache_creation token counts.  [Structure]
 - [Knowledge Base Information Types](knowledge-base-information-types.md) — The seven OKF information types used in this bundle and how they relate.  [Structure]

{copilot_session_usage-0.2.3 → copilot_session_usage-0.3.0}/knowledge/structures/subagent-cost-tracking.md

@@ -5,10 +5,12 @@ description: How subagent costs are logged, aggregated, and correlated with
   parent sessions.
 tags: [subagents, cost-aggregation, parallel-agents, runSubagent]
 timestamp: 2026-06-30T22:00:00Z
-links: [findings/title-jsonl-not-counted-as-model-turn.md,
+links: [findings/2026.07.02-00.00-subagent-logs-runsubagent-prefix.md,
+    findings/2026.07.02-22.00-title-generation-not-counted-as-model-turn.md,
     guides/automation-scripts.md, reference/debug-log-format.md]
 backlinks: [concepts/overview.md, guides/automation-scripts.md,
     guides/cost-optimization.md, reference/debug-log-format.md]
+okf_version: "0.1"
 ---
 
 # Subagent Cost Tracking
@@ -35,6 +37,7 @@ runSubagent-<agent-name>-functions.runSubagent:<id>.jsonl
 Example: `runSubagent-default-functions.runSubagent:19.jsonl`
 
 The `<id>` is a sequential number assigned per `runSubagent` call in the parent session.
+For details, see Finding [`2026.07.02-00.00-subagent-logs-runsubagent-prefix`](../findings/2026.07.02-00.00-subagent-logs-runsubagent-prefix.md).
 
 ## Cost Distribution Pattern
 
@@ -70,7 +73,7 @@ VS Code debug panel totals also match `main.jsonl` because the panel excludes
 well — these calls consume real tokens (typically a few hundred input +
 ~1,000 output from a cheap model) and are intentionally included in the
 tool's total. See Finding
-[`title-jsonl-not-counted-as-model-turn`](../findings/title-jsonl-not-counted-as-model-turn.md).
+[`2026.07.02-22.00-title-generation-not-counted-as-model-turn`](../findings/2026.07.02-22.00-title-generation-not-counted-as-model-turn.md).
 
 This is common for:
 
@@ -80,7 +83,7 @@ This is common for:
 
 Example: a session titled *"Get subagent token costs"* that explores how
 cost tracking works without actually spawning subagents will show 7 files
-but only 2 `.jsonl` files, with `main.jsonl` containing all ~8.7M input
+but only 2 `.jsonl` files (main.jsonl and title-*.jsonl), with `main.jsonl` containing all ~8.7M input
 tokens.
 
 ## Mixed-Model Files and Cost Attribution
@@ -115,7 +118,7 @@ total_cost = sum(estimate_cost(**b, model=m, pricing=pricing) for m, b in per_mo
 
 ## Correlating Subagents to Tasks
 
-The `child_session_ref` event in `main.jsonl` links the numeric ID to the agent name:
+The `child_session_ref` event in `main.jsonl` links the numeric ID to the agent name and session ID:
 
 ```json
 {

{copilot_session_usage-0.2.3 → copilot_session_usage-0.3.0}/knowledge/structures/vscode-copilot-extension.md

@@ -6,10 +6,11 @@ description: How the VS Code Copilot extension stores session logs and what
 tags: [vscode, copilot-extension, paths, workspace-storage, cross-platform]
 timestamp: 2026-07-01T00:00:00Z
 links: [concepts/copilot-cli.md,
-    findings/title-jsonl-not-counted-as-model-turn.md,
+    findings/2026.07.02-22.00-title-generation-not-counted-as-model-turn.md,
     reference/debug-log-format.md]
 backlinks: [concepts/copilot-cli.md, reference/debug-log-format.md,
     structures/session-discovery-algorithm.md]
+okf_version: "0.1"
 ---
 
 # VS Code Copilot Extension Debug Logs
@@ -83,7 +84,7 @@ When the session ID is unknown, match by:
 > the `title-<uuid>.jsonl` file from all metrics (calls, tokens, model turns).
 > `copilot-session-usage` counts it — typically +1 call and a few hundred
 > input + ~1,000 output tokens per session, billed at the title model's rate.
-> See Finding [`title-jsonl-not-counted-as-model-turn`](../findings/title-jsonl-not-counted-as-model-turn.md).
+> See Finding [`2026.07.02-22.00-title-generation-not-counted-as-model-turn`](../findings/2026.07.02-22.00-title-generation-not-counted-as-model-turn.md).
 
 ## Related