From 27cb224c074b56fd5c26252cade653d563d61da0 Mon Sep 17 00:00:00 2001
From: Andrey Avtomonov <andreybavt@gmail.com>
Date: Tue, 9 Jun 2026 23:01:46 +0200
Subject: [PATCH] docs: document isolated ktx project repos

---
 .../content/docs/configuration/ktx-yaml.mdx   | 24 +++----------------
 .../docs/getting-started/quickstart.mdx       |  3 +++
 .../content/docs/guides/reviewing-context.mdx |  7 ++++--
 3 files changed, 11 insertions(+), 23 deletions(-)

diff --git a/docs-site/content/docs/configuration/ktx-yaml.mdx b/docs-site/content/docs/configuration/ktx-yaml.mdx
index db74ffa7..d5dd18c8 100644
--- a/docs-site/content/docs/configuration/ktx-yaml.mdx
+++ b/docs-site/content/docs/configuration/ktx-yaml.mdx
@@ -344,15 +344,14 @@ setup:
 
 ## `storage`
 
-`storage` controls where **ktx** keeps its own state and search index, and how
-state changes are committed. Defaults work for a single-user local project.
+`storage` controls where **ktx** keeps its own state and search index. Defaults
+work for a single-user local project.
 
 ```yaml
 storage:
   state: sqlite          # sqlite | postgres
   search: sqlite-fts5    # sqlite-fts5 | postgres-hybrid
   git:
-    auto_commit: true
     author: "ktx <ktx@example.com>"
 ```
 
@@ -360,8 +359,7 @@ storage:
 |-------|------|---------|---------|
 | `state` | `sqlite` \| `postgres` | `sqlite` | Backend for ktx state. `sqlite` uses `.ktx/db.sqlite`; `postgres` expects a configured Postgres connection. |
 | `search` | `sqlite-fts5` \| `postgres-hybrid` | `sqlite-fts5` | Backend for search indexes. `postgres-hybrid` combines lexical and vector search in Postgres. |
-| `git.auto_commit` | `boolean` | `true` | When `true`, ktx auto-commits changes to the git-backed state store. |
-| `git.author` | `string` | `ktx <ktx@example.com>` | Git author identity for auto-commits. Standard `Name <email>` form. |
+| `git.author` | `string` | `ktx <ktx@example.com>` | Git author identity for commits. Standard `Name <email>` form. |
 
 ## `llm`
 
@@ -608,19 +606,6 @@ agent:
 | `run_research.max_iterations` | `int ≥ 0` | `20` | Maximum tool-call iterations per research run. |
 | `run_research.default_toolset` | `string[]` | `[sl_query, wiki_search, sl_read_source]` | Tool identifiers exposed to the research agent. |
 
-## `memory`
-
-`memory` controls the agent memory subsystem.
-
-```yaml
-memory:
-  auto_commit: true
-```
-
-| Field | Type | Default | Purpose |
-|-------|------|---------|---------|
-| `auto_commit` | `boolean` | `true` | When `true`, ktx auto-commits memory updates to the git-backed store. |
-
 ## A full example
 
 Combining the blocks above:
@@ -645,7 +630,6 @@ storage:
   state: sqlite
   search: sqlite-fts5
   git:
-    auto_commit: true
     author: "ktx <ktx@example.com>"
 llm:
   provider:
@@ -678,8 +662,6 @@ scan:
 agent:
   run_research:
     enabled: true
-memory:
-  auto_commit: true
 ```
 
 ## Validating your config
diff --git a/docs-site/content/docs/getting-started/quickstart.mdx b/docs-site/content/docs/getting-started/quickstart.mdx
index 50059cb6..372bdca0 100644
--- a/docs-site/content/docs/getting-started/quickstart.mdx
+++ b/docs-site/content/docs/getting-started/quickstart.mdx
@@ -338,6 +338,9 @@ separate `ktx` binary on `PATH`. If the CLI path changes, rerun
 ## What setup writes
 
 **ktx** writes plain files so people and agents can review changes in git.
+**ktx** initializes a git repository at the project directory and writes context
+changes there. If the project directory is nested inside another repository,
+**ktx** still keeps its own repo and does not commit to the parent repo.
 
 | Path | Purpose |
 |------|---------|
diff --git a/docs-site/content/docs/guides/reviewing-context.mdx b/docs-site/content/docs/guides/reviewing-context.mdx
index 63d4fceb..26f191b6 100644
--- a/docs-site/content/docs/guides/reviewing-context.mdx
+++ b/docs-site/content/docs/guides/reviewing-context.mdx
@@ -61,11 +61,14 @@ committing the file.
 
 ## A typical review session
 
-The loop above describes the shape. In practice, one review session looks like
-this:
+The loop above describes the shape. Run these commands from the **ktx** project
+directory. **ktx** keeps that directory as its own git repository, even when the
+directory lives inside another repository, so reviewing context changes never
+requires committing to a parent application repo.
 
 ```bash
 # 1. Run ingest on a branch
+cd /path/to/ktx-project
 git checkout -b ingest/2026-05-21
 ktx ingest --all