kmosoti · kmosoti · Jun 7, 2026 · Jun 7, 2026
diff --git a/README.md b/README.md
@@ -10,6 +10,22 @@ The repository is organized as a Markdown-native doctrine graph. Markdown pages
 
 This is a living doctrine repo with support tooling. The goal is not to collect loose notes or ship a product. The goal is to maintain a durable, inspectable, and reusable record of how I want technical work to be structured.
 
+## Generated graph views
+These visuals are generated by `uv run tea-kb build` and checked by GitHub Actions.
+
+![How tea-style works](graph/generated/visualizations/repo-system.svg)
+
+![Research support map](graph/generated/visualizations/research-support.svg)
+
+![Knowledge base growth](graph/generated/visualizations/timeline-overview.svg)
+
+Reviewable generated views:
+- [visualization index](graph/generated/visualizations/README.md)
+- [interactive graph overview](graph/generated/visualizations/overview.html)
+- [graph health report](graph/generated/reports/health.md)
+- [knowledge timeline report](graph/generated/reports/timeline.md)
+- [timeline event feed](graph/generated/timeline.jsonl)
+
 ## Core navigation
 - [docs/repo-scope.md](docs/repo-scope.md)
 - [docs/work-operating-model.md](docs/work-operating-model.md)
@@ -29,6 +45,7 @@ Common commands:
 - `uv run tea-kb build`
 - `uv run tea-kb report`
 - `uv run tea-kb viz overview`
+- `uv run tea-kb viz all`
 
 Tea-themed aliases are available for human convenience:
 - `uv run tea-kb brew` for `build`

diff --git a/docs/decisions/0001-adopt-github-native-second-brain-doctrine.md b/docs/decisions/0001-adopt-github-native-second-brain-doctrine.md
@@ -4,6 +4,8 @@ title: Adopt GitHub-Native Second-Brain Doctrine
 type: decision
 domain: repo-wide
 status: active
+created: 2026-06-07
+updated: 2026-06-07
 summary: >
   Use GitHub-native Markdown as the second-brain substrate for tea-style.
 concepts:

diff --git a/docs/decisions/0002-adopt-markdown-native-doctrine-graph.md b/docs/decisions/0002-adopt-markdown-native-doctrine-graph.md
@@ -4,6 +4,8 @@ title: Adopt Markdown-Native Doctrine Graph
 type: decision
 domain: repo-wide
 status: active
+created: 2026-06-07
+updated: 2026-06-07
 summary: >
   Markdown notes and frontmatter are the source of truth; graph artifacts are generated from visible source files.
 concepts:

diff --git a/docs/decisions/0003-ship-tea-kb-lifecycle-tooling.md b/docs/decisions/0003-ship-tea-kb-lifecycle-tooling.md
@@ -4,6 +4,8 @@ title: Ship TEA KB Lifecycle Tooling
 type: decision
 domain: repo-wide
 status: active
+created: 2026-06-07
+updated: 2026-06-07
 summary: >
   Include a bounded Python package and CLI for validating, building, reporting, visualizing, and exporting the Markdown doctrine graph.
 concepts:

diff --git a/docs/doctrines/engineering-control-spine.md b/docs/doctrines/engineering-control-spine.md
@@ -4,6 +4,8 @@ title: Engineering Control Spine
 type: doctrine
 domain: repo-wide
 status: active
+created: 2026-06-07
+updated: 2026-06-07
 summary: >
   Good systems are easy to reason about, easy to change, hard to misuse, and observable when they fail.
 concepts:

diff --git a/docs/doctrines/systems-should-tell-on-themselves.md b/docs/doctrines/systems-should-tell-on-themselves.md
@@ -4,6 +4,8 @@ title: Systems Should Tell on Themselves
 type: doctrine
 domain: repo-wide
 status: active
+created: 2026-06-07
+updated: 2026-06-07
 summary: >
   Good systems reduce guessing by exposing state, capturing evidence, and making failure modes visible.
 concepts:

diff --git a/docs/doctrines/tea-style-doctrine.md b/docs/doctrines/tea-style-doctrine.md
@@ -4,6 +4,8 @@ title: TEA Style Doctrine
 type: doctrine
 domain: repo-wide
 status: active
+created: 2026-06-07
+updated: 2026-06-07
 summary: >
   tea-style is a Markdown-native engineering doctrine graph with embedded Python lifecycle tooling.
 concepts:

diff --git a/docs/doctrines/typed-encapsulated-architecture-style.md b/docs/doctrines/typed-encapsulated-architecture-style.md
@@ -4,6 +4,8 @@ title: Typed Encapsulated Architecture Style
 type: doctrine
 domain: repo-wide
 status: active
+created: 2026-06-07
+updated: 2026-06-07
 summary: >
   TEA is a decision style for explicit, modular, typed, reviewable, and durable systems.
 concepts:

diff --git a/docs/maps/agent-architecture.md b/docs/maps/agent-architecture.md
@@ -4,6 +4,8 @@ title: Agent Architecture Map
 type: map
 domain: agent-architecture
 status: active
+created: 2026-06-07
+updated: 2026-06-07
 summary: >
   Navigation map for agent architecture doctrine and graph notes.
 concepts:

diff --git a/docs/maps/automation.md b/docs/maps/automation.md
@@ -4,6 +4,8 @@ title: Automation Map
 type: map
 domain: automation
 status: active
+created: 2026-06-07
+updated: 2026-06-07
 summary: >
   Navigation map for automation doctrine and graph notes.
 concepts:

diff --git a/docs/maps/coding.md b/docs/maps/coding.md
@@ -4,6 +4,8 @@ title: Coding Map
 type: map
 domain: coding
 status: active
+created: 2026-06-07
+updated: 2026-06-07
 summary: >
   Navigation map for coding doctrine and graph notes.
 concepts:

diff --git a/docs/maps/engineering-doctrine.md b/docs/maps/engineering-doctrine.md
@@ -4,6 +4,8 @@ title: Engineering Doctrine Map
 type: map
 domain: repo-wide
 status: active
+created: 2026-06-07
+updated: 2026-06-07
 summary: >
   Navigation map for the core TEA doctrine graph.
 concepts:

diff --git a/docs/maps/observability.md b/docs/maps/observability.md
@@ -4,6 +4,8 @@ title: Observability Map
 type: map
 domain: observability
 status: active
+created: 2026-06-07
+updated: 2026-06-07
 summary: >
   Navigation map for observability doctrine and graph notes.
 concepts:

diff --git a/docs/standards/agent-kb-editing-standard.md b/docs/standards/agent-kb-editing-standard.md
@@ -4,6 +4,8 @@ title: Agent KB Editing Standard
 type: standard
 domain: agent-architecture
 status: active
+created: 2026-06-07
+updated: 2026-06-07
 summary: >
   Defines how agents may add or change graph knowledge without silently redefining doctrine.
 concepts:
@@ -38,6 +40,7 @@ Agents may propose graph changes. They must not silently promote inferred doctri
 - Mark inferred edges as proposed unless the user explicitly reviewed them.
 - Do not silently redefine core doctrine.
 - Do not rename IDs casually.
+- Update the `updated` frontmatter date when durable meaning, graph metadata, or relationships change.
 - Run validation before finishing.
 - Update maps only when navigation materially improves.
 
@@ -71,6 +74,7 @@ origin:
 - IDs are stable and meaningful.
 - Concepts reuse existing vocabulary.
 - Edges are justified.
+- `created` and `updated` dates are present and accurate enough for timeline generation.
 - Generated artifacts are updated.
 - Validation passes.
 - Reports were reviewed.

diff --git a/docs/standards/generated-artifact-standard.md b/docs/standards/generated-artifact-standard.md
@@ -4,6 +4,8 @@ title: Generated Artifact Standard
 type: standard
 domain: repo-wide
 status: active
+created: 2026-06-07
+updated: 2026-06-07
 summary: >
   Defines generated graph artifacts, stale checks, determinism, and review expectations.
 concepts:
@@ -34,12 +36,19 @@ Generated artifacts are derived from Markdown/frontmatter. They are committed wh
 - `graph/generated/edges.jsonl`
 - `graph/generated/chunks.jsonl`
 - `graph/generated/concepts.jsonl`
+- `graph/generated/timeline.jsonl`
 - `graph/generated/reports/health.md`
 - `graph/generated/reports/orphan-notes.md`
 - `graph/generated/reports/dense-links.md`
 - `graph/generated/reports/duplicate-concepts.md`
 - `graph/generated/reports/proposed-edges.md`
+- `graph/generated/reports/timeline.md`
 - `graph/generated/visualizations/overview.html`
+- `graph/generated/visualizations/README.md`
+- `graph/generated/visualizations/repo-system.svg`
+- `graph/generated/visualizations/research-support.svg`
+- `graph/generated/visualizations/timeline-overview.svg`
+- `graph/generated/visualizations/concept-timeline-*.svg`
 
 ## Rules / standards
 - Generated artifacts must be deterministic.
@@ -48,6 +57,8 @@ Generated artifacts are derived from Markdown/frontmatter. They are committed wh
 - Reports should be boring, useful, and reviewable.
 - JSONL exports should be stable-sorted by ID or edge tuple.
 - Visualization output should avoid avoidable randomness.
+- Root README diagrams must be generated artifacts, not hand-maintained images.
+- Timeline artifacts must be derived from `created` and `updated` frontmatter dates.
 
 ## Related pages
 - [graph-knowledge-base-standard.md](graph-knowledge-base-standard.md)

diff --git a/docs/standards/graph-knowledge-base-standard.md b/docs/standards/graph-knowledge-base-standard.md
@@ -4,6 +4,8 @@ title: Graph Knowledge Base Standard
 type: standard
 domain: repo-wide
 status: active
+created: 2026-06-07
+updated: 2026-06-07
 summary: >
   Defines graph source units, node types, edge types, IDs, frontmatter, and generated artifacts.
 concepts:
@@ -91,10 +93,19 @@ title: Example
 type: note
 domain: repo-wide
 status: active
+created: 2026-06-07
+updated: 2026-06-07
 concepts:
   - evidence
 ```
 
+## Timeline metadata
+Every authored graph node should carry:
+- `created`: the date the note, concept, decision, standard, map, example, or antipattern entered the graph.
+- `updated`: the latest meaningful doctrine or metadata update date.
+
+Use ISO `YYYY-MM-DD` dates. Generated timeline artifacts use these fields rather than Git history so timelines remain portable across forks, exports, and future search systems.
+
 ## Related pages
 - [graph/schema.md](../../graph/schema.md)
 - [graph-linking-standard.md](graph-linking-standard.md)

diff --git a/docs/standards/graph-linking-standard.md b/docs/standards/graph-linking-standard.md
@@ -4,6 +4,8 @@ title: Graph Linking Standard
 type: standard
 domain: repo-wide
 status: active
+created: 2026-06-07
+updated: 2026-06-07
 summary: >
   Defines when to create semantic graph edges and when to rely on Markdown links.
 concepts:

diff --git a/docs/standards/python-type-discipline.md b/docs/standards/python-type-discipline.md
@@ -4,6 +4,8 @@ title: Python Type Discipline
 type: standard
 domain: coding
 status: active
+created: 2026-06-07
+updated: 2026-06-07
 summary: >
   Defines how tea_kb uses Pydantic, dataclasses, NewType, StrEnum, Protocol, and standard collections.
 concepts:

diff --git a/docs/standards/visualization-standard.md b/docs/standards/visualization-standard.md
@@ -4,6 +4,8 @@ title: Visualization Standard
 type: standard
 domain: repo-wide
 status: active
+created: 2026-06-07
+updated: 2026-06-07
 summary: >
   Defines graph visualizations as diagnostic artifacts, not decorative output.
 concepts:
@@ -34,6 +36,9 @@ Visualizations are diagnostic. They should answer a question.
 - Show node type, domain, and edge labels.
 - Link visual nodes back to source Markdown when practical.
 - Generated visualizations must be deterministic enough for review.
+- Root README visuals must be regenerated by `tea-kb build`, not edited as screenshots.
+- Timeline views should be split by major concept when a single feed would become noisy.
+- SVG is preferred for README-level diagrams because it is GitHub-native, diffable, and deterministic.
 
 ## Good visualizations
 - concept neighborhood
@@ -43,6 +48,10 @@ Visualizations are diagnostic. They should answer a question.
 - orphan note map
 - dense-link warning map
 - proposed-edge review map
+- repository system map
+- research support map
+- knowledge base growth timeline
+- major concept timeline
 
 ## Anti-patterns
 - huge all-node/all-edge views with no diagnostic purpose