diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml index 40bd2e11..7a7b5d03 100644 --- a/.github/ISSUE_TEMPLATE/config.yml +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -10,5 +10,5 @@ contact_links: url: https://docs.kaelio.com/ktx/docs/community/support about: Full guide on where to ask what — Slack vs. GitHub Issues vs. docs. - name: Security issues - url: https://github.com/Kaelio/ktx-ai-data-agents-context/security/advisories/new + url: https://github.com/Kaelio/ktx/security/advisories/new about: Report security vulnerabilities privately via GitHub Security Advisories. Please do not file security issues publicly. diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 4c981e98..cace9460 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -212,12 +212,12 @@ jobs: uses: codecov/codecov-action@75cd11691c0faa626561e295848008c8a7dddffe # v5.5.4 with: token: ${{ secrets.CODECOV_TOKEN }} - slug: Kaelio/ktx-ai-data-agents-context + slug: Kaelio/ktx files: ./packages/cli/coverage/lcov.info flags: typescript name: typescript disable_search: true - fail_ci_if_error: true + fail_ci_if_error: false - name: Warn when Codecov token is missing for TypeScript if: env.CODECOV_TOKEN_CONFIGURED != 'true' @@ -231,12 +231,12 @@ jobs: uses: codecov/codecov-action@75cd11691c0faa626561e295848008c8a7dddffe # v5.5.4 with: token: ${{ secrets.CODECOV_TOKEN }} - slug: Kaelio/ktx-ai-data-agents-context + slug: Kaelio/ktx files: ./coverage/python.xml flags: python name: python disable_search: true - fail_ci_if_error: true + fail_ci_if_error: false - name: Warn when Codecov token is missing for Python if: env.CODECOV_TOKEN_CONFIGURED != 'true' diff --git a/.github/workflows/star-history.yml b/.github/workflows/star-history.yml index e8156407..b7d90c43 100644 --- a/.github/workflows/star-history.yml +++ b/.github/workflows/star-history.yml @@ -35,7 +35,7 @@ jobs: set -euo pipefail # cachebust forces star-history to regenerate instead of serving its # own server-side cache; --location follows the slug-normalizing 301. - url="https://api.star-history.com/svg?repos=Kaelio/ktx-ai-data-agents-context&type=Date&cachebust=${GITHUB_RUN_ID}-${GITHUB_RUN_ATTEMPT}" + url="https://api.star-history.com/svg?repos=Kaelio/ktx&type=Date&cachebust=${GITHUB_RUN_ID}-${GITHUB_RUN_ATTEMPT}" curl --fail --location --silent --show-error \ --retry 3 --retry-delay 5 --max-time 60 \ -o assets/star-history.svg.new "$url" diff --git a/AGENTS.md b/AGENTS.md index 7acbb732..ffe324bb 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -64,6 +64,25 @@ When rules conflict, follow this order: 4. Code quality: types, readable boundaries, focused modules 5. Performance where it matters +## Opinionated Product Defaults + +- **MUST**: Prefer one canonical behavior over configurable alternatives. A new + flag, config field, environment variable, mode, strategy option, adapter hook, + or fallback path is a product feature and must be justified by an explicit + user request or a real correctness requirement. +- **MUST NOT**: Add speculative flexibility for imagined users, migrations, + review preferences, local workflows, or "just in case" scenarios. If the + requested behavior can work with one solid default, implement that default. +- **MUST NOT**: Add boolean switches that create two runtime paths unless both + paths are essential and the user explicitly asked for the choice. Boolean + policy knobs are especially suspect because they double the state space and + test surface. +- **MUST**: When a design seems to need a new option, first try to remove the + need by choosing the stronger default, tightening the invariant, or failing + clearly. Ask the user before adding the option if it still seems necessary. +- **MUST**: Delete obsolete branches, tests, docs, and config when removing a + behavior. Do not preserve dormant compatibility paths. + ## Repository Shape **ktx** is a pnpm + uv workspace. @@ -159,6 +178,91 @@ and naming asymmetries are bugs in waiting — see [`docs/code-design.md`](docs/code-design.md). Treat the `MUST` / `MUST NOT` rules there with the same weight as the ones in this file. +## Design Reasoning Defaults + +When proposing a design, an approach, or any non-trivial change, apply these +defaults and run the self-check before presenting it. They encode the +corrections users most often have to make; reaching these conclusions +autonomously — without being asked the leading question — is the bar. + +- **MUST**: Optimize for the best outcome, not for an unstated constraint. Do not + silently adopt "smallest change", "least effort", "cheapest", or "least user + intervention" as the goal unless the user said so. Default to the most correct, + durable solution, and present cost / effort / scope as information for the user + to weigh — not as a ceiling you impose on their behalf. +- **MUST**: Separate one-time cost from recurring cost before discarding an + option. A fixed cost paid once (a setup-time computation, an extra LLM call + during setup, a contract change) to make every later run cheaper or more + correct is usually worth it. Do not reject it with recurring-cost reasoning; + quantify both sides. (Example smell: "don't add an LLM call to a cost-cutting + feature" — wrong when the call is one-time and the savings recur.) +- **MUST**: Treat a user's example as a representative of a class, not as the + spec. Design for the general population the example stands for, then stress-test + against deliberately different instances — another warehouse, dialect, stack + layout, or input shape — before committing. If a design only works because of an + incidental property of the example (e.g. "the noise happened to be in a separate + schema *on this demo*"), it is curve-fitting; generalize it or state the + assumption explicitly. +- **MUST**: Prefer deriving from the system's own state over enumerating cases. + Favor an allowlist computed from declared/observed state (config, scanned + catalog, query log, the user's own inputs) over a denylist of known-bad + specifics (particular tables, schemas, tools, or vendors). A hardcoded or + hand-maintained list of external specifics is a smell: it rots and fails on the + next stack. The only acceptable static patterns are genuinely universal + invariants (e.g. DB-engine system catalogs) and ktx's own self-emitted + signatures. +- **MUST**: Give each capability one implementation and route every caller + through it. When some behavior — running a query, resolving a credential or + config reference, authenticating, selecting a dialect, loading config — + already has a working implementation that some call sites use, make new or + divergent call sites depend on that path instead of standing up a second one. + Parallel implementations of one capability drift apart silently: a fix, a + newly supported input, or an added case lands on one path and not the other, + so one entry point (a CLI command, an MCP tool, an ingest stage) succeeds + while another fails on the same input. When two paths already do the same + job, collapse onto the shared one and delete the duplicate instead of + keeping both. When fixing a defect that lives on one path, fix the shared + implementation; do not patch the symptom on a forked branch, which preserves + the divergence you set out to remove. +- **SHOULD**: Before inventing an abstraction or hand-rolling structural logic, + search for what already exists and reuse it — the codebase's canonical + representation (a structured ref/key type) instead of a parallel string scheme, + and a mandated/available tool (e.g. `sqlglot` for SQL structure; see + [SQL and Structured Parsing](#sql-and-structured-parsing)) instead of + hand-parsing. Normalize ambiguous input to the canonical form at the boundary; + do not carry the ambiguity downstream. This is the single-source-of-truth / DRY + item from the Priority Hierarchy applied at design time. + +Before presenting a design, answer these explicitly: + +1. Am I optimizing for a goal the user actually stated, or one I assumed? +2. Does this generalize beyond the example in front of me? Name a real case where + it would break. +3. Am I enumerating known-bad cases when I could derive scope from the system's + own declared/observed state? +4. Is there an existing canonical representation or mandated tool I should reuse + instead of building or parsing my own? +5. Am I discarding the better option on a weak or misapplied constraint + (one-time vs recurring cost, "more surface area", "more work now")? +6. Does another entry point already perform this operation through a shared + implementation? If so, am I routing through that path instead of forking a + parallel one — and if I'm fixing a bug, am I fixing the shared layer rather + than one branch? +7. Am I adding a user-visible option or alternate runtime path that the user did + not ask for? If yes, can one opinionated default solve the problem instead? +8. Does this option multiply behavior by caller path, config value, or local + state? If yes, remove it unless it is explicitly required. + +A user question that nudges toward an alternative ("would X help?", "should I +always do Y?", "will you hardcode Z?") is a signal that a better option exists. +Investigate the implied direction and reason it through *before* defending the +original proposal — and prefer to have asked yourself the question first. + +Example: If generated context changes should be saved, choose one save policy +and route ingest, setup, memory, indexing, and docs through it. Do not add an +`auto_commit`-style switch unless the user explicitly asks for staged-only runs +and accepts the extra runtime path. + ## TypeScript Standards - Use Node 22+ and pnpm workspace commands. @@ -278,7 +382,8 @@ use `PascalCase` without the suffix. ## Telemetry -**ktx** ships PostHog usage telemetry. When adding commands or events: +**ktx** ships PostHog usage telemetry. Catalog telemetry events use strict +schemas. When adding commands or events: - **MUST NOT**: Add fields that carry user data — file paths, hostnames, environment values, SQL text, schema/table/column names, error messages, @@ -295,6 +400,24 @@ use `PascalCase` without the suffix. of collected data changes. Adding another event with no new field types needs no docs change. +### Error reports + +**ktx** also sends PostHog Error Tracking `$exception` events when telemetry is +enabled. This channel is separate from the strict catalog event schema and is +used only for exception diagnostics. + +`$exception` events may include stack frames, error class names, raw error +messages, cause chains, `source`, `handled`, `fatal`, runtime version fields, +OS/runtime fields, and the hashed `projectId` when known. Stack frames may +include local file paths and the local username when those appear in paths. + +`$exception` events must never intentionally include secrets, credentials, +database URLs, auth headers, raw argv, raw environment values, SQL text, +schema/table/column names as explicit properties, customer row data, user prompt +text, or raw MCP arguments. Reporters must redact call-site-provided secret +snapshots and common static credential patterns before the SDK serializes the +exception. + ## Documentation and Specs - Keep public documentation in `README.md`, package READMEs, example READMEs, @@ -381,8 +504,8 @@ rather than silently skipping it. - **MUST**: Disable monospace ligatures on every surface that uses the `var(--font-mono)` family (Geist Mono). Geist Mono fuses `--` into an em-dash glyph that visually eats the adjacent space, so prompts like - `npx skills add Kaelio/ktx-ai-data-agents-context --skill ktx` render as - `Kaelio/ktx-ai-data-agents-context--skill ktx`. + `npx skills add Kaelio/ktx --skill ktx` render as + `Kaelio/ktx--skill ktx`. - **MUST**: When adding a new container that renders user-visible monospace text outside `` / `
` (e.g. a styled `
`
   for a copyable prompt), verify the global ligature-off rule in
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 157921f0..a4fb3040 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -8,8 +8,8 @@ layout, and verification commands, see the
 ## How to contribute
 
 1. Browse open issues labeled
-   [`good first issue`](https://github.com/Kaelio/ktx-ai-data-agents-context/labels/good%20first%20issue)
-   or [`help wanted`](https://github.com/Kaelio/ktx-ai-data-agents-context/labels/help%20wanted).
+   [`good first issue`](https://github.com/Kaelio/ktx/labels/good%20first%20issue)
+   or [`help wanted`](https://github.com/Kaelio/ktx/labels/help%20wanted).
 2. Comment on the issue to claim it. A maintainer will confirm scope and
    assign it to you.
 3. For changes not covered by an existing issue, open one first so we can
@@ -82,7 +82,7 @@ page for the full guide. The short version:
 - **Feature requests**: use the
   [Feature request](.github/ISSUE_TEMPLATE/feature_request.yml) template.
 - **Security**: report privately via
-  [GitHub Security Advisories](https://github.com/Kaelio/ktx-ai-data-agents-context/security/advisories/new),
+  [GitHub Security Advisories](https://github.com/Kaelio/ktx/security/advisories/new),
   not as a public issue.
 
 ## Code of conduct
diff --git a/README.md b/README.md
index d417d77a..3f704f04 100644
--- a/README.md
+++ b/README.md
@@ -8,21 +8,25 @@
 
 

   npm version
-  Codecov
-  Tests
+  Codecov
+  Tests
   Documentation
   Join the ktx Slack community
-  License
-  Y Combinator P25
+  License
+  Y Combinator P25
 

 
 

   Quickstart ·
   CLI Reference ·
-  Agent Setup ·
+  Agent Setup ·
   Slack
 

 
+

+  Built and maintained by Kaelio
+

+
 ---
 
 **ktx** is a self-improving context layer that teaches agents how to query your
@@ -30,8 +34,9 @@ warehouse accurately - from approved metric definitions, joinable columns, and
 business knowledge it builds and maintains for you.
 
 > [!NOTE]
-> Run **ktx** with your own LLM API keys or a **Claude Pro/Max** subscription.
-> No extra usage billing from **ktx**.
+> Run **ktx** with your own LLM API keys or a local agent sign-in — a
+> **Claude Pro/Max** subscription through Claude Code, or your local Codex
+> authentication. No extra usage billing from **ktx**.
 
 

   
@@ -130,7 +135,7 @@ Agent integration ready: yes (codex:project)
 > your project directory:
 >
 > ```text
-> Run npx skills add Kaelio/ktx-ai-data-agents-context --skill ktx and use the ktx skill to install
+> Run npx skills add Kaelio/ktx --skill ktx and use the ktx skill to install
 > and configure ktx in this project.
 > ```
 
@@ -138,6 +143,14 @@ Agent integration ready: yes (codex:project)
 > If `ktx status` prints `ktx mcp start --project-dir ...`, run it before
 > opening your agent client.
 
+## Upgrading
+
+Re-run the global install with the `@latest` tag:
+
+```bash
+npm install -g @kaelio/ktx@latest
+```
+
 ## First commands
 
 | Command | Purpose |
@@ -175,8 +188,9 @@ then the current directory. Pass `--project-dir ` when scripting.
   No. **ktx** runs locally. The only data leaving your machine is what you
   send to the LLM provider you configured.
 - **Which LLM backends are supported?**
-  Anthropic API, Google Vertex AI, AI Gateway, and the local Claude Code
-  session through the Claude Agent SDK. See
+  Anthropic API, Google Vertex AI, AI Gateway, the local Claude Code session
+  through the Claude Agent SDK, and your local Codex authentication through the
+  Codex SDK. See
   [LLM configuration](https://docs.kaelio.com/ktx/docs/guides/llm-configuration).
 - **How is ktx different from a dbt or MetricFlow semantic layer?**
   **ktx** *ingests* those layers and combines them with raw-table
@@ -195,13 +209,13 @@ then the current directory. Pass `--project-dir ` when scripting.
 - [The Context Layer](https://docs.kaelio.com/ktx/docs/concepts/the-context-layer)
 - [Building Context](https://docs.kaelio.com/ktx/docs/guides/building-context)
 - [CLI Reference](https://docs.kaelio.com/ktx/docs/cli-reference/ktx)
-- [Agent Quickstart](https://docs.kaelio.com/ktx/docs/ai-resources/agent-quickstart)
+- [AI Resources](https://docs.kaelio.com/ktx/docs/community/ai-resources)
 - [Community & Support](https://docs.kaelio.com/ktx/docs/community/support)
 
 ## Community
 
 - **[Slack](https://join.slack.com/t/ktxcommunity/shared_invite/zt-3y9b44m1x-LVyNNJD5nwaZHq4XS29LMQ)** — ask questions, share what you're building, and chat with maintainers.
-- **[GitHub Issues](https://github.com/Kaelio/ktx-ai-data-agents-context/issues)** — report bugs and request features.
+- **[GitHub Issues](https://github.com/Kaelio/ktx/issues)** — report bugs and request features.
 - **[Contributing](https://docs.kaelio.com/ktx/docs/community/contributing)** — set up the repo, run tests, and open a PR.
 
 ## Development
@@ -245,11 +259,17 @@ uv run pytest -q
 
 ## Telemetry
 
-**ktx** collects anonymous usage telemetry from interactive CLI runs to
-improve setup, command reliability, and data-agent workflows. No file paths,
-hostnames, SQL, schema names, error messages, or argv are recorded. See
-[Telemetry](https://docs.kaelio.com/ktx/docs/community/telemetry) for the
-event catalog and opt-out options.
+**ktx** collects privacy-conscious usage telemetry to understand installs and
+improve setup, command reliability, and data-agent workflows. Catalog telemetry
+events do not record file paths, hostnames, SQL, schema names, table names,
+column names, error messages, raw environment values, or argv. Error reports use
+PostHog Error Tracking and can include stack frames and raw error messages,
+which may contain local file paths or the local username in those paths.
+**ktx** redacts secrets, credentials, database URLs, auth headers, argv, raw
+environment values, SQL text, row data, and user-typed prompt or MCP argument
+text from the explicit `$exception` payload. See
+[Telemetry](https://docs.kaelio.com/ktx/docs/community/telemetry) for the event
+catalog and opt-out options.
 
 ## License
 
@@ -258,7 +278,7 @@ event catalog and opt-out options.
 ## Star History
 
 

-  
+  
     ktx Star History Chart
   
 

diff --git a/SECURITY.md b/SECURITY.md
index 7d0c1909..da90c1a5 100644
--- a/SECURITY.md
+++ b/SECURITY.md
@@ -5,7 +5,7 @@
 If you believe you've found a security vulnerability in KTX, please report it
 **privately** through GitHub Security Advisories:
 
-[Report a vulnerability](https://github.com/Kaelio/ktx-ai-data-agents-context/security/advisories/new)
+[Report a vulnerability](https://github.com/Kaelio/ktx/security/advisories/new)
 
 If you cannot use GitHub Security Advisories, email `support@kaelio.com`
 instead. Please do **not** open a public issue, post in the KTX Slack, or
diff --git a/assets/star-history.svg b/assets/star-history.svg
index 16b5fc6a..8fa7bc08 100644
--- a/assets/star-history.svg
+++ b/assets/star-history.svg
@@ -1 +1 @@
-star-history.comMay 17May 24May 31 100200300400500600kaelio/ktxStar HistoryDateGitHub Stars
+star-history.comMay 17May 24May 31Jun 07 200400600800kaelio/ktxStar HistoryDateGitHub Stars
diff --git a/docs-site/app/docs/layout.tsx b/docs-site/app/docs/layout.tsx
index ff7d69a9..5f684ea0 100644
--- a/docs-site/app/docs/layout.tsx
+++ b/docs-site/app/docs/layout.tsx
@@ -2,10 +2,21 @@ import { source } from "@/lib/source";
 import { DocsLayout } from "fumadocs-ui/layouts/docs";
 import type { ReactNode } from "react";
 import { baseOptions } from "@/app/layout.config";
+import { GitHubStars } from "@/components/github-stars";
 
 export default function Layout({ children }: { children: ReactNode }) {
   return (
-    
+    
+            
+          

+        ),
+      }}
+    >
       {children}
     
   );
diff --git a/docs-site/app/global.css b/docs-site/app/global.css
index 929e06b4..d6d9ada6 100644
--- a/docs-site/app/global.css
+++ b/docs-site/app/global.css
@@ -869,6 +869,147 @@ body::after {
   50% { opacity: 0.65; transform: scale(0.9); }
 }
 
+/* ═══════════════════════════════════════════
+   GitHub star widget (navbar)
+   Split pill: GitHub mark + "Star" │ gold star + count.
+   ═══════════════════════════════════════════ */
+.ktx-stars {
+  display: inline-flex;
+  align-items: stretch;
+  height: 32px;
+  border-radius: 999px;
+  border: 1px solid var(--color-fd-border);
+  background: color-mix(in oklch, var(--color-fd-card) 72%, transparent);
+  backdrop-filter: blur(8px);
+  -webkit-backdrop-filter: blur(8px);
+  font-family: var(--font-display), var(--font-sans), sans-serif;
+  font-size: 13px;
+  line-height: 1;
+  color: var(--color-fd-foreground);
+  text-decoration: none;
+  overflow: hidden;
+  box-shadow: 0 1px 2px rgba(27, 27, 24, 0.04);
+  transition:
+    transform 0.3s var(--ktx-ease),
+    box-shadow 0.3s var(--ktx-ease),
+    border-color 0.3s ease;
+  animation: ktx-stars-in 0.5s var(--ktx-ease) both;
+}
+
+@keyframes ktx-stars-in {
+  from { opacity: 0; transform: translateY(-4px); }
+  to { opacity: 1; transform: translateY(0); }
+}
+
+.ktx-stars:hover {
+  transform: translateY(-1px);
+  border-color: color-mix(in oklch, var(--color-fd-primary) 45%, var(--color-fd-border));
+  box-shadow:
+    0 6px 18px -8px rgba(14, 116, 144, 0.28),
+    0 1px 2px rgba(27, 27, 24, 0.05);
+}
+
+.ktx-stars:focus-visible {
+  outline: 2px solid var(--color-fd-ring);
+  outline-offset: 2px;
+}
+
+.dark .ktx-stars {
+  background: color-mix(in oklch, var(--color-fd-card) 60%, transparent);
+  box-shadow: 0 1px 2px rgba(0, 0, 0, 0.25);
+}
+
+.dark .ktx-stars:hover {
+  border-color: rgba(34, 211, 238, 0.4);
+  box-shadow:
+    0 6px 18px -8px rgba(34, 211, 238, 0.3),
+    0 1px 2px rgba(0, 0, 0, 0.3);
+}
+
+.ktx-stars-seg {
+  display: inline-flex;
+  align-items: center;
+  gap: 6px;
+  padding: 0 11px;
+}
+
+.ktx-stars-seg--count {
+  border-left: 1px solid var(--color-fd-border);
+  background: color-mix(in oklch, var(--color-fd-primary) 6%, transparent);
+  transition: background 0.3s var(--ktx-ease);
+}
+
+.ktx-stars:hover .ktx-stars-seg--count {
+  background: color-mix(in oklch, var(--color-fd-primary) 12%, transparent);
+}
+
+.ktx-stars-gh {
+  width: 15px;
+  height: 15px;
+  opacity: 0.85;
+}
+
+.ktx-stars-text {
+  font-weight: 500;
+  letter-spacing: -0.01em;
+}
+
+.ktx-stars-star {
+  width: 14px;
+  height: 14px;
+  fill: #f5b301;
+  transition: transform 0.3s var(--ktx-ease), filter 0.3s var(--ktx-ease);
+}
+
+.ktx-stars:hover .ktx-stars-star {
+  transform: scale(1.18) rotate(-8deg);
+  filter: drop-shadow(0 1px 4px rgba(245, 179, 1, 0.55));
+}
+
+.ktx-stars-count {
+  font-weight: 600;
+  font-variant-numeric: tabular-nums;
+  color: var(--color-fd-foreground);
+}
+
+/* Skeleton shown only on the rare cold (uncached) fetch */
+.ktx-stars--skeleton {
+  animation: none;
+}
+
+.ktx-stars-skeleton-bar {
+  display: inline-block;
+  width: 26px;
+  height: 11px;
+  border-radius: 4px;
+  background: linear-gradient(
+    90deg,
+    var(--color-fd-muted) 25%,
+    color-mix(in oklch, var(--color-fd-muted-foreground) 28%, var(--color-fd-muted)) 50%,
+    var(--color-fd-muted) 75%
+  );
+  background-size: 200% 100%;
+  animation: ktx-stars-shimmer 1.4s ease-in-out infinite;
+}
+
+@keyframes ktx-stars-shimmer {
+  from { background-position: 200% 0; }
+  to { background-position: -200% 0; }
+}
+
+/* Compact on phones: drop the "Star" word, keep mark + count */
+@media (max-width: 640px) {
+  .ktx-stars-text { display: none; }
+  .ktx-stars-seg { padding: 0 9px; }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .ktx-stars { animation: none; transition: none; }
+  .ktx-stars:hover { transform: none; }
+  .ktx-stars:hover .ktx-stars-star { transform: none; }
+  .ktx-stars-skeleton-bar { animation: none; }
+}
+
 /* Dot grid */
 .dot-grid {
   background-image: radial-gradient(
diff --git a/docs-site/app/layout.config.tsx b/docs-site/app/layout.config.tsx
index 3245ab09..4e91b559 100644
--- a/docs-site/app/layout.config.tsx
+++ b/docs-site/app/layout.config.tsx
@@ -1,22 +1,13 @@
 import type { BaseLayoutProps } from "fumadocs-ui/layouts/shared";
-import { GitHubIcon } from "@/components/github-icon";
 import { Logo } from "@/components/logo";
 import { SlackIcon } from "@/components/slack-icon";
 
 export const baseOptions: BaseLayoutProps = {
   nav: {
-    title: ,
+    title: Logo,
     transparentMode: "top",
   },
   links: [
-    {
-      type: "icon",
-      label: "GitHub",
-      icon: ,
-      text: "GitHub",
-      url: "https://github.com/kaelio/ktx",
-      external: true,
-    },
     {
       type: "icon",
       label: "Join the ktx Slack community",
diff --git a/docs-site/components/diagram-studio/flows.ts b/docs-site/components/diagram-studio/flows.ts
index cddf75cb..e63cc512 100644
--- a/docs-site/components/diagram-studio/flows.ts
+++ b/docs-site/components/diagram-studio/flows.ts
@@ -305,8 +305,8 @@ export const runtimeEdges: Edge[] = [
     sourceHandle: "to-context",
     target: "context",
     targetHandle: "in",
-    type: "default",
-    label: "search",
+    type: "smoothstep",
+    label: "search + read",
     ...labelBg,
     style: edgeStyle,
     markerStart: marker,
@@ -318,7 +318,7 @@ export const runtimeEdges: Edge[] = [
     sourceHandle: "to-warehouse",
     target: "warehouse",
     targetHandle: "in",
-    type: "default",
+    type: "smoothstep",
     label: "read-only",
     ...labelBg,
     style: edgeStyle,
diff --git a/docs-site/components/github-stars.tsx b/docs-site/components/github-stars.tsx
new file mode 100644
index 00000000..d3b328a3
--- /dev/null
+++ b/docs-site/components/github-stars.tsx
@@ -0,0 +1,93 @@
+import { Suspense } from "react";
+import { GitHubIcon } from "@/components/github-icon";
+
+const REPO = "kaelio/ktx";
+const REPO_URL = `https://github.com/${REPO}`;
+const API_URL = `https://api.github.com/repos/${REPO}`;
+
+async function fetchStarCount(): Promise {
+  try {
+    const res = await fetch(API_URL, {
+      headers: { Accept: "application/vnd.github+json" },
+      // Revalidate hourly. GitHub's unauthenticated REST limit is 60 req/h per
+      // IP, so a single cached server-side fetch keeps the count fresh while
+      // never exposing visitors to rate limits or layout shift.
+      next: { revalidate: 3600 },
+    });
+    if (!res.ok) return null;
+    const data = (await res.json()) as { stargazers_count?: unknown };
+    return typeof data.stargazers_count === "number"
+      ? data.stargazers_count
+      : null;
+  } catch {
+    return null;
+  }
+}
+
+/** Compact, GitHub-style count: 847 → "847", 1234 → "1.2k", 12345 → "12.3k". */
+function formatStars(count: number): string {
+  if (count < 1000) return count.toLocaleString("en-US");
+  const thousands = count / 1000;
+  const rounded =
+    thousands >= 100 ? Math.round(thousands) : Math.round(thousands * 10) / 10;
+  return `${rounded}k`;
+}
+
+function StarGlyph() {
+  return (
+    
+  );
+}
+
+async function StarsContent() {
+  const count = await fetchStarCount();
+  const label =
+    count === null
+      ? "Star ktx on GitHub"
+      : `Star ktx on GitHub — ${count.toLocaleString("en-US")} stars`;
+
+  return (
+    
+      
+        
+        Star
+      
+      {count !== null && (
+        
+          
+          {formatStars(count)}
+        
+      )}
+    
+  );
+}
+
+function StarsSkeleton() {
+  return (
+