feat: rename state dir .kq to .kqs with legacy migration

Author: bimawa

.gitignore

@@ -25,7 +25,7 @@ __pycache__/
 /models/
 
 # Local knowledge graph state
-.kq/
+.kqs/
 
 /.crew/
 /.crew

.kiro/steering/conventions.md

@@ -15,7 +15,7 @@ VideoCatDoc/                    # корневой репозиторий про
 ├── README.md                   # описание knowledge-репозитория
 ├── docs/                       # база знаний (markdown)
 ├── tasks/                      # задачи (TASK-NNN.md)
-└── .kq/                        # sqlite-vec DB + кеш модели
+└── .kqs/                       # sqlite-vec DB + кеш модели
 ```
 
 ### Задачи

.kiro/steering/principles.md

@@ -80,7 +80,7 @@ Push — только по команде `kqs push`.
 ### P-008: Trace Graph is a Cache
 
 **Level:** MUST
-**Rule:** SQLite-граф трассировки — это кеш. Источник истины — .md файлы с Front Matter. При конфликте графа и .md побеждает .md. Пользователь может удалить `.kq/` и пересобрать граф.
+**Rule:** SQLite-граф трассировки — это кеш. Источник истины — .md файлы с Front Matter. При конфликте графа и .md побеждает .md. Пользователь может удалить `.kqs/` и пересобрать граф.
 **Reason:** Никакого lock-in. Пользователь всегда владеет данными.
 **Applies to:** SPEC, TASKS, EXEC
 

Cargo.toml

@@ -4,7 +4,7 @@ members = ["kqs", "kq-core", "kq-embeddings", "kq-llm", "kq-config"]
 
 [workspace.package]
 edition = "2024"
-version = "0.1.1"
+version = "0.1.2"
 authors = ["kq team"]
 license = "MIT OR Apache-2.0"
 repository = "https://github.com/bimawa/KnowledgeQuery"

README.md

@@ -85,7 +85,7 @@ kqs doc list
 
 ## Document Types & the Document Chain
 
-Every template in `.kq/templates/` carries a specific semantic load — the type is chosen
+Every template in `.kqs/templates/` carries a specific semantic load — the type is chosen
 by what question the document answers, not by preference. The types form a chain:
 each next type refines the previous one, from business intent down to the data
 specification that code implements.
@@ -386,7 +386,7 @@ kq-config/         # knowledge.toml parsing
 
 ```
 <project>/
-├── .kq/
+├── .kqs/
 │   ├── knowledge.toml      # config
 │   ├── knowledge.db        # SQLite: FTS + vectors + trace graph
 │   ├── events/             # CRDT task events
@@ -403,9 +403,9 @@ kq-config/         # knowledge.toml parsing
 Tasks use CRDT events instead of overwrites:
 
 ```
-create       → .kq/events/TASK-001/20260709T100000Z-create.md
-assign alex  → .kq/events/TASK-001/20260709T110000Z-assign-alex.md
-move review  → .kq/events/TASK-001/20260709T120000Z-move-review.md
+create       → .kqs/events/TASK-001/20260709T100000Z-create.md
+assign alex  → .kqs/events/TASK-001/20260709T110000Z-assign-alex.md
+move review  → .kqs/events/TASK-001/20260709T120000Z-move-review.md
 ```
 
 **Why:** no merge conflicts, status is computed by replay,

kq-config/src/lib.rs

@@ -17,6 +17,20 @@ pub fn default_knowledge_path() -> PathBuf {
 /// 3. Fall back to `~/.knowledge/` (with tilde expansion).
 ///
 /// The `--repo` CLI flag should be passed as `custom` to override auto-detection.
+/// Path to the `~/.kqs/current-repo` marker, migrating the legacy
+/// `~/.kq/current-repo` file in place when present.
+pub fn current_repo_marker() -> PathBuf {
+    let Some(home) = home_dir() else {
+        return PathBuf::from(".kqs/current-repo");
+    };
+    let new = home.join(".kqs/current-repo");
+    let old = home.join(".kq/current-repo");
+    if old.exists() && !new.exists() {
+        let _ = std::fs::rename(&old, &new);
+    }
+    new
+}
+
 pub fn repo_path(custom: Option<&str>) -> Result<PathBuf> {
     if let Some(custom_path) = custom
         && !custom_path.is_empty()
@@ -42,17 +56,15 @@ pub fn repo_path(custom: Option<&str>) -> Result<PathBuf> {
         }
     }
 
-    // Fallback: check ~/.kq/current-repo marker
-    if let Some(home) = home_dir() {
-        let marker = home.join(".kq/current-repo");
-        if marker.exists() {
-            let content = std::fs::read_to_string(&marker).unwrap_or_default();
-            let path = content.trim().to_string();
-            if !path.is_empty() {
-                let expanded = expand_tilde(Path::new(&path));
-                if expanded.join("knowledge.toml").exists() {
-                    return Ok(expanded);
-                }
+    // Fallback: check ~/.kqs/current-repo marker
+    let marker = current_repo_marker();
+    if marker.exists() {
+        let content = std::fs::read_to_string(&marker).unwrap_or_default();
+        let path = content.trim().to_string();
+        if !path.is_empty() {
+            let expanded = expand_tilde(Path::new(&path));
+            if expanded.join("knowledge.toml").exists() {
+                return Ok(expanded);
             }
         }
     }

kq-core/src/docs.rs

@@ -3,8 +3,6 @@ use std::path::Path;
 
 use anyhow::{Context, Result};
 
-const TEMPLATES_SUBDIR: &str = ".kq/templates";
-
 const GROK_CATEGORIES: &[(&str, &str)] = &[
     ("01-business-foundation", "Business Foundation"),
     ("02-product-ux", "Product & UX"),
@@ -258,10 +256,10 @@ pub fn init_with_docs(path: &Path) -> Result<()> {
 pub fn generate_doc(path: &Path, doc_type: &str, title: &str) -> Result<String> {
     // Support any type: known DOC_TYPES OR custom template file
     if !DOC_TYPES.iter().any(|(t, _)| *t == doc_type) {
-        let template_file = path.join(TEMPLATES_SUBDIR).join(format!("{}.md", doc_type));
+        let template_file = crate::state_dir(path).join("templates").join(format!("{}.md", doc_type));
         if !template_file.exists() {
             anyhow::bail!(
-                "Unknown doc type '{}'. Use one of: {} or create .kq/templates/{}.md",
+                "Unknown doc type '{}'. Use one of: {} or create .kqs/templates/{}.md",
                 doc_type,
                 DOC_TYPES.iter().map(|(t, _)| *t).collect::<Vec<_>>().join(", "),
                 doc_type
@@ -333,10 +331,10 @@ pub fn list_docs(path: &Path) -> Result<Vec<(String, String)>> {
     Ok(results)
 }
 
-/// Initialize template files in `.kq/templates/` for all document types.
+/// Initialize template files in `.kqs/templates/` for all document types.
 /// Creates the directory and writes default template `.md` files.
 pub fn init_templates(repo_path: &Path) -> Result<()> {
-    let templates_dir = repo_path.join(TEMPLATES_SUBDIR);
+    let templates_dir = crate::state_dir(repo_path).join("templates");
     fs::create_dir_all(&templates_dir)
         .with_context(|| format!("Failed to create templates dir at {}", templates_dir.display()))?;
 
@@ -351,9 +349,9 @@ pub fn init_templates(repo_path: &Path) -> Result<()> {
     Ok(())
 }
 
-/// Load template body from `.kq/templates/<type>.md` file, falling back to hardcoded template.
+/// Load template body from `.kqs/templates/<type>.md` file, falling back to hardcoded template.
 fn load_template(repo_path: &Path, doc_type: &str) -> Result<(&'static str, String)> {
-    let template_file = repo_path.join(TEMPLATES_SUBDIR).join(format!("{}.md", doc_type));
+    let template_file = crate::state_dir(repo_path).join("templates").join(format!("{}.md", doc_type));
 
     if template_file.exists() {
         let body = fs::read_to_string(&template_file)
@@ -371,7 +369,7 @@ pub fn templates_list(repo_path: Option<&Path>) -> Vec<String> {
 
     // Scan custom templates from filesystem
     if let Some(path) = repo_path {
-        let templates_dir = path.join(TEMPLATES_SUBDIR);
+        let templates_dir = crate::state_dir(path).join("templates");
         if templates_dir.is_dir()
             && let Ok(entries) = fs::read_dir(&templates_dir)
         {

kq-core/src/init.rs

@@ -8,7 +8,7 @@ use kq_config::KnowledgeConfig;
 ///
 /// This is the core implementation backing `kqs init`. It:
 /// - Resolves the target directory (default: `~/.knowledge/`)
-/// - Creates the directory structure (`docs/`, `tasks/`, `.kq/`)
+/// - Creates the directory structure (`docs/`, `tasks/`, `.kqs/`)
 /// - Initializes a git repository
 /// - Writes a default `knowledge.toml` configuration
 /// - Stages all files and creates an initial commit
@@ -50,14 +50,15 @@ pub fn init(path: Option<PathBuf>, remote: Option<String>, force: bool) -> Resul
     // 3. Create directory structure
     fs::create_dir_all(target_path.join("docs")).context("Failed to create docs/ directory")?;
     fs::create_dir_all(target_path.join("tasks")).context("Failed to create tasks/ directory")?;
-    fs::create_dir_all(target_path.join(".kq")).context("Failed to create .kq/ directory")?;
+    fs::create_dir_all(crate::state_dir(&target_path)).context("Failed to create .kqs/ directory")?;
     // 3.1 Create default templates
     crate::docs::init_templates(&target_path)?;
     // 3.2 Create events directory
-    fs::create_dir_all(target_path.join(".kq/events")).context("Failed to create .kq/events/ directory")?;
+    fs::create_dir_all(crate::state_dir(&target_path).join("events"))
+        .context("Failed to create .kqs/events/ directory")?;
 
     // 3.5 Create SQLite database with FTS5 schema
-    let db_path = target_path.join(".kq/knowledge.db");
+    let db_path = crate::state_dir(&target_path).join("knowledge.db");
     crate::db::init_db(&db_path).context("Failed to initialize FTS database")?;
 
     // 4. Initialize git repository

kq-core/src/lib.rs

@@ -16,9 +16,28 @@ pub mod typespec;
 pub mod vector;
 pub mod watcher;
 
-use std::path::Path;
+use std::path::{Path, PathBuf};
 use std::sync::OnceLock;
 
+/// Internal state directory name inside a knowledge repo.
+pub const STATE_DIR: &str = ".kqs";
+
+/// Resolve the state directory (`.kqs`) for a knowledge repo.
+///
+/// On first use, migrates a legacy `.kq` directory in place so existing
+/// repositories keep their database, events and templates.
+pub fn state_dir(repo_path: &Path) -> PathBuf {
+    let new = repo_path.join(STATE_DIR);
+    let old = repo_path.join(".kq");
+    if old.is_dir() && !new.exists() {
+        match std::fs::rename(&old, &new) {
+            Ok(()) => eprintln!("[kqs] Migrated legacy state directory .kq -> {STATE_DIR}"),
+            Err(e) => eprintln!("[kqs] Failed to migrate .kq -> {STATE_DIR}: {e}"),
+        }
+    }
+    new
+}
+
 /// Operating mode for kqs.
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub enum KqsMode {

kq-core/src/task.rs

@@ -80,9 +80,9 @@ fn parse_event(content: &str) -> Result<TaskEvent> {
     Ok(event)
 }
 
-/// Write an event file to `.kq/events/<task_id>/`.
+/// Write an event file to `.kqs/events/<task_id>/`.
 fn write_event(repo_path: &Path, task_id: &str, op: &str, value: &str) -> Result<TaskEvent> {
-    let events_dir = repo_path.join(".kq/events").join(task_id);
+    let events_dir = crate::state_dir(repo_path).join("events").join(task_id);
     fs::create_dir_all(&events_dir).context("Failed to create events directory")?;
 
     let timestamp = chrono::Utc::now().format("%Y%m%dT%H%M%SZ").to_string();
@@ -395,7 +395,7 @@ fn read_task_file(path: &Path) -> Result<Task> {
 /// Create a new task with the given title, priority, and optional assignee.
 ///
 /// Creates `tasks/TASK-NNN.md` with minimal frontmatter (title, priority, created)
-/// and a create event in `.kq/events/TASK-NNN/`.
+/// and a create event in `.kqs/events/TASK-NNN/`.
 pub fn task_new(title: &str, status: Status, priority: Priority, assignee: &str) -> Result<Task> {
     let tasks_dir = tasks_dir()?;
     fs::create_dir_all(&tasks_dir).context("Failed to create tasks directory")?;
@@ -422,7 +422,7 @@ pub fn task_new(title: &str, status: Status, priority: Priority, assignee: &str)
     }
     update_task_refs(&repo, &id)?;
 
-    let state = replay_events(&repo.join(".kq/events").join(&id)).unwrap_or_default();
+    let state = replay_events(&crate::state_dir(&repo).join("events").join(&id)).unwrap_or_default();
 
     Ok(Task {
         id,
@@ -443,7 +443,7 @@ pub(crate) fn update_task_refs(repo: &Path, id: &str) -> Result<()> {
     }
     let content = fs::read_to_string(&task_path)?;
 
-    let state = replay_events(&repo.join(".kq/events").join(id)).unwrap_or_default();
+    let state = replay_events(&crate::state_dir(&repo).join("events").join(id)).unwrap_or_default();
 
     // Extract immutable fields from existing frontmatter
     let (orig_title, orig_priority, orig_created) =