fix: correct snippet line-number labels and add utf-8 encoding

- Fix edit_doc_file snippet labels: `i + start + 1` double-counted the
  start offset; changed to `i + 1` in both str_replace and insert branches
- Add encoding="utf-8" to _write_generation_metadata write_text call
- Document that metadata.json is written only on close_session in
  IDE_DRIVEN_GUIDE.md and SKILL.md

Author: mambo-wang

IDE_DRIVEN_GUIDE.md

@@ -245,6 +245,8 @@ Subsequent call to analyze_repo after code changes:
 1. **Git strategy**: Read `commit_id` from `metadata.json`, run `git diff` against current HEAD, also check `git status` to capture uncommitted changes (modified + untracked files)
 2. **Mtime strategy** (fallback for non-git repos): Walk source files and compare modification times against `timestamp` in `metadata.json`
 
+> **Note**: `metadata.json` is written only when `close_session` is called. If a session ends without calling `close_session`, no baseline exists and the next `analyze_repo` silently falls back to full analysis. Always call `close_session` at the end of the workflow to ensure incremental updates work.
+
 **Return structure**:
 
 ```json

codewiki/mcp/server.py

@@ -570,7 +570,8 @@ def _write_generation_metadata(session: SessionState) -> None:
             },
         }
         (output_dir / "metadata.json").write_text(
-            json.dumps(metadata, indent=2, ensure_ascii=False)
+            json.dumps(metadata, indent=2, ensure_ascii=False),
+            encoding="utf-8",
         )
     except Exception as e:
         logger.warning("Failed to write metadata.json: %s", e)

codewiki/mcp/tools/doc_writer.py

@@ -173,7 +173,7 @@ async def handle_edit_doc_file(
         lines = new_content.split("\n")
         start = max(0, replacement_line - 4)
         end = min(len(lines), start + new_str.count("\n") + 9)
-        snippet = "\n".join(f"{i + start + 1:6}\t{lines[i]}" for i in range(start, end))
+        snippet = "\n".join(f"{i + 1:6}\t{lines[i]}" for i in range(start, end))
 
     elif command == "insert":
         insert_line = arguments.get("insert_line", 0)
@@ -190,7 +190,7 @@ async def handle_edit_doc_file(
 
         start = max(0, insert_line - 4)
         end = min(len(lines), start + len(new_str_lines) + 8)
-        snippet = "\n".join(f"{i + start + 1:6}\t{lines[i]}" for i in range(start, end))
+        snippet = "\n".join(f"{i + 1:6}\t{lines[i]}" for i in range(start, end))
 
     else:
         return json.dumps({"error": f"Unknown command: {command}. Use str_replace, insert, or undo."})

skills/codewiki-wiki-generator/SKILL.md

@@ -127,6 +127,8 @@ When documentation has already been generated for a repository (`metadata.json`
 
 **Change detection strategy**: Prefers `git diff` (comparing commit SHA + checking for uncommitted workspace changes); falls back to comparing file modification times for non-git repositories.
 
+> **Note**: `metadata.json` is written only when `close_session` is called. Sessions that end without `close_session` leave no baseline, so the next `analyze_repo` falls back to full analysis. Always call `close_session` at the end of the workflow.
+
 **Incremental update workflow**:
 
 1. Call `analyze_repo` and check the returned `changes` field or read the `changes.json` file