fix: security hardening and doc accuracy for v0.12.0

- Add path traversal validation in recordProvenanceSources and CheckSourceDivergence
- Add vault-staleness and vault-source-divergence to sanitizeContextTags
- Sanitize divergence context output to prevent prompt injection via paths
- Strip newlines from kaizen frontmatter values to prevent YAML injection
- Update timing claims to realistic values in README, CHANGELOG, npm/README
- Fix npm/README stale MCP tool count (12 → 17) and add missing tools

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: sgx-labs

CHANGELOG.md

@@ -470,7 +470,7 @@ Security hardening, crash recovery, search improvements, UX polish, and every ho
 
 ### Changed
 
-- **README rewritten** — pain-first opening, architecture diagram, feature matrix, competitor comparison table, honest benchmarks (removed aspirational token claim)
+- **README rewritten** — pain-first opening, architecture diagram, feature matrix, competitor comparison table, updated benchmarks
 - **Schema v3** — adds `session_recovery` table; auto-migrates from v2
 - **MCP tool list updated** — setup now shows all 11 tools with accurate descriptions
 
@@ -489,7 +489,7 @@ Self-diagnosing retrieval, pinned notes, keyword fallback, vault privacy structu
   - `get_session_context` — one-call orientation: pinned notes + latest handoff + recent activity + stats
   - `recent_activity` — recently modified notes (clamped to 50)
 - **`same ask`** — ask questions, get answers FROM your notes with source citations. Uses a local Ollama LLM to synthesize answers from semantically relevant notes. Auto-detects the best available chat model. 100% local, no cloud APIs. Example: `same ask "what did we decide about authentication?"`
-- **`same demo`** — interactive demo that creates a temporary vault with 6 realistic sample notes, indexes them, runs search, and showcases `same ask`. Works without Ollama (keyword-only mode). See SAME in action in under 60 seconds.
+- **`same demo`** — interactive demo that creates a temporary vault with 6 realistic sample notes, indexes them, runs search, and showcases `same ask`. Works without Ollama (keyword-only mode).
 - **`same tutorial`** — modular learn-by-doing system with 6 lessons: semantic search, decisions, pinning, privacy tiers, RAG chat, and session handoffs. Run all lessons (`same tutorial`) or jump to any topic (`same tutorial search`, `same tutorial pin`). Creates real notes and runs real commands — you learn the CLI by using it.
 - **SAME Lite (keyword-only mode)** — SAME now works without Ollama. When Ollama is unavailable, `same init` offers keyword-only mode using SQLite FTS5. All features work — search, ask, demo, tutorial — with keyword matching instead of semantic search. Install Ollama later and `same reindex` upgrades to full semantic mode. Zero dependencies beyond the binary.
 - **Project-aware init** — `same init` now detects existing project documentation (README.md, docs/, ARCHITECTURE.md, CLAUDE.md, .cursorrules, ADR/) and offers to index them. Zero new notes required — your project already has context.

README.md

@@ -28,7 +28,7 @@ Or via npm (all platforms): `npm install -g @sgx-labs/same`
 
 **Installed via npm?** Update with `npx same@latest` or `npm update -g @sgx-labs/same`.
 
-## See It Work (30 seconds)
+## See It Work
 
 ```bash
 same demo
@@ -127,7 +127,7 @@ Your markdown notes get embedded and stored in SQLite. When your AI starts a ses
 | MRR | **0.949** (right note first, almost every time) |
 | Prompt overhead | **<200ms** |
 | Binary size | **~12MB** |
-| Setup time | **<60 seconds** |
+| Setup time | **Under 2 minutes** |
 
 ## Add to Your AI Tool
 

cmd/same/kaizen_cmd.go

@@ -224,9 +224,12 @@ func runKaizenAdd(description, agent, status string) error {
 	}
 
 	// Build frontmatter
+	// SECURITY: strip newlines from frontmatter values to prevent YAML injection
+	safeTitle := strings.ReplaceAll(strings.ReplaceAll(description, "\n", " "), "\r", " ")
+
 	var content strings.Builder
 	content.WriteString("---\n")
-	content.WriteString(fmt.Sprintf("title: %s\n", description))
+	content.WriteString(fmt.Sprintf("title: %s\n", safeTitle))
 	content.WriteString("content_type: kaizen\n")
 	content.WriteString(fmt.Sprintf("status: %s\n", status))
 	if agent != "" {

internal/hooks/staleness_check.go

@@ -77,7 +77,8 @@ func buildDivergenceContext(db *store.DB, vaultPath string) string {
 		lines = append(lines, fmt.Sprintf("- %s (source: %s changed %s)", d.NotePath, sourceBase, agoStr))
 	}
 
-	return strings.Join(lines, "\n")
+	// SECURITY: sanitize output to prevent prompt injection via crafted paths
+	return sanitizeContextTags(strings.Join(lines, "\n"))
 }
 
 // formatDivergenceAge formats a duration as a relative time string for divergence context.

internal/hooks/text_processing.go

@@ -206,6 +206,8 @@ func sanitizeContextTags(text string) string {
 		"session-bootstrap",
 		"vault-handoff",
 		"vault-decisions",
+		"vault-staleness",
+		"vault-source-divergence",
 		"same-diagnostic",
 		// F16: Additional tags used by AI systems that could enable prompt injection
 		"system-reminder",

internal/mcp/server.go

@@ -681,6 +681,10 @@ func recordProvenanceSources(notePath string, explicitSources []string) {
 		if srcPath == "" {
 			continue
 		}
+		// SECURITY: validate path to prevent traversal (e.g. "../../etc/passwd")
+		if safeVaultPath(srcPath) == "" {
+			continue
+		}
 		hash := ""
 		fullPath := filepath.Join(vaultRoot, srcPath)
 		if content, err := os.ReadFile(fullPath); err == nil {
@@ -1518,18 +1522,22 @@ func handleSaveKaizen(ctx context.Context, req *mcp.CallToolRequest, input saveK
 	}
 
 	// Build content
+	// SECURITY: strip newlines from frontmatter values to prevent YAML injection
+	safeTitle := strings.ReplaceAll(strings.ReplaceAll(description, "\n", " "), "\r", " ")
+	safeArea := strings.ReplaceAll(strings.ReplaceAll(strings.TrimSpace(input.Area), "\n", " "), "\r", " ")
+
 	var content strings.Builder
 	mcpHeader := "<!-- Note saved via SAME MCP tool. Review before trusting. -->\n"
 	content.WriteString(mcpHeader)
 	content.WriteString("---\n")
-	content.WriteString(fmt.Sprintf("title: %s\n", description))
+	content.WriteString(fmt.Sprintf("title: %s\n", safeTitle))
 	content.WriteString("content_type: kaizen\n")
 	content.WriteString("status: open\n")
 	if agent != "" {
 		content.WriteString(fmt.Sprintf("agent: %s\n", agent))
 	}
-	if input.Area != "" {
-		content.WriteString(fmt.Sprintf("area: %s\n", strings.TrimSpace(input.Area)))
+	if safeArea != "" {
+		content.WriteString(fmt.Sprintf("area: %s\n", safeArea))
 	}
 	content.WriteString("tags: [kaizen]\n")
 	content.WriteString("---\n\n")

internal/store/sources.go

@@ -168,6 +168,11 @@ func (db *DB) CheckSourceDivergence(vaultPath string) ([]DivergenceResult, error
 			return nil, fmt.Errorf("scan divergence row: %w", err)
 		}
 
+		// SECURITY: validate stored path to prevent traversal reads outside vault
+		clean := filepath.ToSlash(filepath.Clean(sourcePath))
+		if strings.HasPrefix(clean, "..") || filepath.IsAbs(clean) || strings.Contains(clean, "\x00") {
+			continue
+		}
 		fullPath := filepath.Join(vaultPath, sourcePath)
 		content, err := os.ReadFile(fullPath)
 		if err != nil {

npm/README.md

@@ -11,9 +11,9 @@ Your AI agent forgets everything between sessions. SAME fixes that. It indexes y
 - **Session handoffs** — your agent writes what it did, the next session picks up where it left off
 - **Decision log** — decisions are saved and surfaced automatically in future sessions
 - **`same ask`** — RAG chat over your vault with source citations
-- **`same demo`** — try it in 60 seconds, creates a sandbox, cleans up after
+- **`same demo`** — try it interactively, creates a sandbox, cleans up after
 
-## 12 MCP Tools
+## 17 MCP Tools
 
 | Tool | Type | Description |
 |------|------|-------------|
@@ -29,6 +29,11 @@ Your AI agent forgets everything between sessions. SAME fixes that. It indexes y
 | `save_note` | write | Create or update a note (optional `agent` attribution) |
 | `save_decision` | write | Log a project decision (optional `agent` attribution) |
 | `create_handoff` | write | Create a session handoff note (optional `agent` attribution) |
+| `save_kaizen` | write | Log improvement items with provenance tracking |
+| `mem_consolidate` | write | Consolidate related notes via LLM |
+| `mem_brief` | read | Generate orientation briefing |
+| `mem_health` | read | Vault health with trust analysis |
+| `mem_forget` | write | Suppress a note from search results |
 
 ## MCP Configuration