openclew 0.1.0 → 0.2.0

package/README.md

@@ -70,13 +70,13 @@ L1 answers "should I read this?" L2 answers "what do I need to know?" L3 is ther
 
 | Type | Location | Role | Mutability |
 |------|----------|------|------------|
-| **Permanent** | `doc/_SUBJECT.md` | Living knowledge (architecture, conventions, decisions) | Updated over time |
+| **Living** | `doc/_SUBJECT.md` | Living knowledge (architecture, conventions, decisions) | Updated over time |
 | **Log** | `doc/log/YYYY-MM-DD_subject.md` | Frozen facts (what happened, what was decided) | Never modified |
 
-**Permanents** are your project's brain — they evolve as the project evolves.
+**Living docs** are your project's brain — they evolve as the project evolves.
 **Logs** are your project's journal — immutable records of what happened and why.
 
-Together, they form the thread. The permanent docs tell you where you are. The logs tell you how you got here.
+Together, they form the thread. The living docs tell you where you are. The logs tell you how you got here.
 
 ---
 
@@ -93,7 +93,7 @@ mkdir -p doc/log
 Download from [`templates/`](templates/) or create manually:
 
 <details>
-<summary><b>templates/permanent.md</b> — for living knowledge</summary>
+<summary><b>templates/living.md</b> — for living knowledge</summary>
 
 ```markdown
 <!-- L1_START -->
@@ -181,7 +181,7 @@ keywords: [tag1, tag2, tag3]
 ### 3. Write your first doc
 
 ```bash
-cp templates/permanent.md doc/_ARCHITECTURE.md
+cp templates/living.md doc/_ARCHITECTURE.md
 ```
 
 Edit it — describe your project's architecture. Fill in L1 (metadata), L2 (summary), skip L3 if you don't need it yet.
@@ -195,7 +195,7 @@ Add this to your `CLAUDE.md`, `.cursorrules`, or `AGENTS.md`:
 
 Documentation lives in `doc/`. Each doc has 3 levels (L1/L2/L3).
 - Read L1 first to decide if you need more
-- Permanent docs: `doc/_*.md` (living knowledge, updated)
+- Living docs: `doc/_*.md` (living knowledge, updated)
 - Logs: `doc/log/YYYY-MM-DD_*.md` (frozen facts, never modified)
 - Index: `doc/_INDEX.md` (auto-generated, start here)
 ```
@@ -263,7 +263,7 @@ doc/
 - **Shared knowledge** — Same docs for humans and AI. One source, multiple readers.
 - **SSOT** (Single Source of Truth) — Each piece of information lives in one place.
 - **Logs are immutable** — Once written, never modified. Frozen facts.
-- **Permanents are living** — They evolve as the project evolves.
+- **Living docs evolve** — They evolve as the project evolves.
 - **Index is auto-generated** — Never edit `_INDEX.md` manually.
 
 ---

package/bin/openclew.js

@@ -10,14 +10,25 @@ openclew — Long Life Memory for LLMs
 
 Usage:
   openclew init                    Set up openclew in the current project
-  openclew new <title>             Create a new permanent doc
-  openclew log <title>             Create a new session log
+  openclew new <title>             Create a living doc (evolves with the project)
+  openclew log <title>             Create a session log (frozen facts)
+  openclew checkout                End-of-session summary + log creation
   openclew index                   Regenerate doc/_INDEX.md
   openclew help                    Show this help
 
 Options:
   --no-hook                        Skip pre-commit hook installation (init)
   --no-inject                      Skip instruction file injection (init)
+
+Getting started:
+  npx openclew init                1. Set up doc/ + guide + examples + git hook
+  # Edit doc/_ARCHITECTURE.md      2. Replace the example with your project's architecture
+  openclew new "API design"        3. Create your own living docs
+  git commit                       4. Index auto-regenerates on commit
+
+Docs have 3 levels: L1 (metadata) → L2 (summary) → L3 (details).
+Agents read L1 to decide what's relevant, then L2 for context.
+More at: https://github.com/openclew/openclew
 `.trim();
 
 if (!command || command === "help" || command === "--help" || command === "-h") {
@@ -29,6 +40,7 @@ const commands = {
   init: () => require("../lib/init"),
   new: () => require("../lib/new-doc"),
   log: () => require("../lib/new-log"),
+  checkout: () => require("../lib/checkout"),
   index: () => require("../lib/index-gen"),
 };
 

package/hooks/generate-index.py

@@ -2,7 +2,7 @@
 """
 openclew index generator.
 
-Scans doc/_*.md (permanents) and doc/log/*.md (logs),
+Scans doc/_*.md (living docs) and doc/log/*.md (logs),
 parses L1 metadata blocks, and generates doc/_INDEX.md.
 
 Usage:
@@ -63,17 +63,17 @@ def parse_l1(filepath):
 
 
 def collect_docs(doc_dir):
-    """Collect permanents and logs with their L1 metadata."""
-    permanents = []
+    """Collect living docs and logs with their L1 metadata."""
+    living_docs = []
     logs = []
 
-    # Permanent docs: doc/_*.md
+    # Living docs: doc/_*.md
     for f in sorted(doc_dir.glob("_*.md")):
         if f.name == "_INDEX.md":
             continue
         meta = parse_l1(f)
         if meta:
-            permanents.append((f, meta))
+            living_docs.append((f, meta))
 
     # Log docs: doc/log/*.md
     log_dir = doc_dir / "log"
@@ -83,10 +83,10 @@ def collect_docs(doc_dir):
             if meta:
                 logs.append((f, meta))
 
-    return permanents, logs
+    return living_docs, logs
 
 
-def generate_index(doc_dir, permanents, logs):
+def generate_index(doc_dir, living_docs, logs):
     """Generate _INDEX.md content."""
     now = datetime.now().strftime("%Y-%m-%d %H:%M")
     lines = [
@@ -97,13 +97,13 @@ def generate_index(doc_dir, permanents, logs):
         f"",
     ]
 
-    # Permanents section
-    lines.append("## Permanent docs")
+    # Living docs section
+    lines.append("## Living docs")
     lines.append("")
-    if permanents:
+    if living_docs:
         lines.append("| Document | Subject | Status | Category |")
         lines.append("|----------|---------|--------|----------|")
-        for f, meta in permanents:
+        for f, meta in living_docs:
             name = f.name
             subject = meta.get("subject", "—")
             status = meta.get("status", "—")
@@ -111,7 +111,7 @@ def generate_index(doc_dir, permanents, logs):
             rel_path = f.relative_to(doc_dir.parent)
             lines.append(f"| [{name}]({rel_path}) | {subject} | {status} | {category} |")
     else:
-        lines.append("_No permanent docs yet. Create one with `templates/permanent.md`._")
+        lines.append("_No living docs yet. Create one with `templates/living.md`._")
     lines.append("")
 
     # Logs section (last 20)
@@ -137,7 +137,7 @@ def generate_index(doc_dir, permanents, logs):
 
     # Stats
     lines.append("---")
-    lines.append(f"**{len(permanents)}** permanent docs, **{len(logs)}** logs.")
+    lines.append(f"**{len(living_docs)}** living docs, **{len(logs)}** logs.")
     lines.append("")
 
     return "\n".join(lines)
@@ -145,12 +145,12 @@ def generate_index(doc_dir, permanents, logs):
 
 def main():
     doc_dir = find_doc_dir()
-    permanents, logs = collect_docs(doc_dir)
-    index_content = generate_index(doc_dir, permanents, logs)
+    living_docs, logs = collect_docs(doc_dir)
+    index_content = generate_index(doc_dir, living_docs, logs)
 
     index_path = doc_dir / "_INDEX.md"
     index_path.write_text(index_content, encoding="utf-8")
-    print(f"Generated {index_path} ({len(permanents)} permanents, {len(logs)} logs)")
+    print(f"Generated {index_path} ({len(living_docs)} living docs, {len(logs)} logs)")
 
 
 if __name__ == "__main__":

package/lib/checkout.js

@@ -0,0 +1,288 @@
+/**
+ * openclew checkout — end-of-session summary + log creation.
+ *
+ * 1. Collect git activity (today's commits, uncommitted changes)
+ * 2. Display summary table
+ * 3. Create a session log pre-filled with the activity
+ * 4. Regenerate the index
+ */
+
+const fs = require("fs");
+const path = require("path");
+const { execSync } = require("child_process");
+const { logContent, slugifyLog, today } = require("./templates");
+const { readConfig } = require("./config");
+
+const PROJECT_ROOT = process.cwd();
+const DOC_DIR = path.join(PROJECT_ROOT, "doc");
+const LOG_DIR = path.join(DOC_DIR, "log");
+
+function run(cmd) {
+  try {
+    return execSync(cmd, { cwd: PROJECT_ROOT, encoding: "utf-8" }).trim();
+  } catch {
+    return "";
+  }
+}
+
+function collectGitActivity() {
+  const date = today();
+
+  // Today's commits
+  const commitLog = run(
+    `git log --since="${date} 00:00" --format="%h %s" --no-merges`
+  );
+  const commits = commitLog
+    ? commitLog.split("\n").filter((l) => l.trim())
+    : [];
+
+  // Uncommitted changes
+  const status = run("git status --porcelain");
+  const uncommitted = status ? status.split("\n").filter((l) => l.trim()) : [];
+
+  // Files changed today (committed)
+  const changedFiles = run(
+    `git diff --name-only HEAD~${Math.max(commits.length, 1)}..HEAD 2>/dev/null`
+  );
+  const files = changedFiles
+    ? changedFiles.split("\n").filter((l) => l.trim())
+    : [];
+
+  // Today's logs already created
+  const existingLogs = fs.existsSync(LOG_DIR)
+    ? fs.readdirSync(LOG_DIR).filter((f) => f.startsWith(date))
+    : [];
+
+  // Living docs
+  const livingDocs = fs.existsSync(DOC_DIR)
+    ? fs.readdirSync(DOC_DIR).filter((f) => f.startsWith("_") && f !== "_INDEX.md" && f.endsWith(".md"))
+    : [];
+
+  return { date, commits, uncommitted, files, existingLogs, livingDocs };
+}
+
+function extractActions(commits) {
+  // Group commits by type (feat, fix, refactor, docs, etc.)
+  return commits.map((c) => {
+    const match = c.match(/^([a-f0-9]+)\s+(\w+)(?:\(([^)]*)\))?:\s*(.+)$/);
+    if (match) {
+      return {
+        hash: match[1],
+        type: match[2],
+        scope: match[3] || "",
+        desc: match[4],
+      };
+    }
+    // Non-conventional commit
+    const parts = c.match(/^([a-f0-9]+)\s+(.+)$/);
+    return {
+      hash: parts ? parts[1] : "",
+      type: "other",
+      scope: "",
+      desc: parts ? parts[2] : c,
+    };
+  });
+}
+
+function typeLabel(type) {
+  const labels = {
+    feat: "Feature",
+    fix: "Fix",
+    refactor: "Refactor",
+    docs: "Doc",
+    test: "Test",
+    build: "Build",
+    chore: "Chore",
+  };
+  return labels[type] || type.charAt(0).toUpperCase() + type.slice(1);
+}
+
+function displaySummary(activity) {
+  const { date, commits, uncommitted, existingLogs, livingDocs } = activity;
+  const actions = extractActions(commits);
+
+  console.log(`\nopenclew checkout — ${date}\n`);
+
+  if (actions.length === 0 && uncommitted.length === 0) {
+    console.log("  Nothing to report — no commits or changes today.");
+    console.log("");
+    return null;
+  }
+
+  // Summary table
+  if (actions.length > 0) {
+    console.log("  Commits today:");
+    console.log(
+      "  ┌─────┬──────────────────────────────────────────────┬─────┐"
+    );
+    console.log(
+      "  │ Sta │ Action                                       │ Com │"
+    );
+    console.log(
+      "  ├─────┼──────────────────────────────────────────────┼─────┤"
+    );
+    for (const a of actions) {
+      const label = `${typeLabel(a.type)} : ${a.desc}`;
+      const truncated = label.length > 44 ? label.slice(0, 43) + "…" : label;
+      const padded = truncated.padEnd(44);
+      console.log(`  │ ✅  │ ${padded} │ 🟢  │`);
+    }
+    console.log(
+      "  └─────┴──────────────────────────────────────────────┴─────┘"
+    );
+    console.log("");
+  }
+
+  if (uncommitted.length > 0) {
+    console.log(`  Uncommitted changes: ${uncommitted.length} file(s)`);
+    for (const line of uncommitted.slice(0, 10)) {
+      console.log(`    ${line}`);
+    }
+    if (uncommitted.length > 10) {
+      console.log(`    ... and ${uncommitted.length - 10} more`);
+    }
+    console.log("");
+  }
+
+  // Documentation status
+  if (existingLogs.length > 0) {
+    console.log(`  📗 Today's logs: ${existingLogs.join(", ")}`);
+  } else {
+    console.log("  📕 No log created today");
+  }
+  console.log("");
+
+  // Living docs reminder
+  if (livingDocs.length > 0) {
+    console.log("  📚 Living docs — check if any need updating:");
+    for (const doc of livingDocs) {
+      console.log(`     ${doc}`);
+    }
+    console.log("");
+  }
+
+  return actions;
+}
+
+function generateSessionLog(activity, actions) {
+  const { date } = activity;
+
+  // Build a descriptive title from actions
+  let sessionTitle;
+  if (actions.length === 1) {
+    sessionTitle = actions[0].desc;
+  } else if (actions.length > 1) {
+    const types = [...new Set(actions.map((a) => typeLabel(a.type)))];
+    sessionTitle = types.join(" + ") + " session";
+  } else {
+    sessionTitle = "Work session";
+  }
+
+  // Build pre-filled log content
+  const keywords = [
+    ...new Set(actions.map((a) => a.scope).filter(Boolean)),
+  ];
+  const keywordsStr =
+    keywords.length > 0 ? `[${keywords.join(", ")}]` : "[]";
+
+  const commitList = actions
+    .map((a) => `- ${typeLabel(a.type)}: ${a.desc} (${a.hash})`)
+    .join("\n");
+
+  const content = `<!-- L1_START -->
+# L1 - Metadata
+date: ${date}
+type: ${actions.length === 1 ? actions[0].type === "fix" ? "Bug" : "Feature" : "Feature"}
+subject: ${sessionTitle}
+short_story: ${actions.map((a) => a.desc).join(". ")}.
+status: Done
+category:
+keywords: ${keywordsStr}
+<!-- L1_END -->
+
+---
+
+<!-- L2_START -->
+# L2 - Summary
+
+## Objective
+<!-- Why this work was undertaken -->
+
+## What was done
+${commitList}
+
+## Result
+<!-- Outcome — what works now that didn't before -->
+<!-- L2_END -->
+
+---
+
+<!-- L3_START -->
+# L3 - Details
+
+<!-- Technical details, code changes, debugging steps... -->
+<!-- L3_END -->
+`;
+
+  const slug = slugifyLog(sessionTitle);
+  const filename = `${date}_${slug}.md`;
+  const filepath = path.join(LOG_DIR, filename);
+
+  if (fs.existsSync(filepath)) {
+    console.log(`  Log already exists: doc/log/${filename}`);
+    return null;
+  }
+
+  if (!fs.existsSync(LOG_DIR)) {
+    console.log("  No doc/log/ directory. Run 'openclew init' first.");
+    return null;
+  }
+
+  fs.writeFileSync(filepath, content, "utf-8");
+  console.log(`  📝 Created doc/log/${filename}`);
+  console.log("     Pre-filled with today's commits. Edit to add context.");
+  return filename;
+}
+
+function regenerateIndex() {
+  const indexScript = path.join(DOC_DIR, "generate-index.py");
+  if (!fs.existsSync(indexScript)) return;
+
+  try {
+    execSync(`python3 "${indexScript}" "${DOC_DIR}"`, { stdio: "pipe" });
+    console.log("  📋 Regenerated doc/_INDEX.md");
+  } catch {
+    // Silent — index will be regenerated on next commit anyway
+  }
+}
+
+function main() {
+  if (!fs.existsSync(DOC_DIR)) {
+    console.error("No doc/ directory found. Run 'openclew init' first.");
+    process.exit(1);
+  }
+
+  if (!readConfig(PROJECT_ROOT)) {
+    console.warn("Warning: no .openclew.json found. Run 'openclew init' first.\n");
+  }
+
+  const activity = collectGitActivity();
+  const actions = displaySummary(activity);
+
+  if (!actions || actions.length === 0) {
+    return;
+  }
+
+  // Create session log
+  console.log("─── Log ───");
+  const created = generateSessionLog(activity, actions);
+
+  // Regenerate index
+  if (created) {
+    regenerateIndex();
+  }
+
+  console.log("");
+}
+
+main();

package/lib/config.js

@@ -0,0 +1,34 @@
+/**
+ * Read/write .openclew.json config at project root.
+ */
+
+const fs = require("fs");
+const path = require("path");
+
+const CONFIG_FILE = ".openclew.json";
+
+function configPath(projectRoot) {
+  return path.join(projectRoot || process.cwd(), CONFIG_FILE);
+}
+
+function readConfig(projectRoot) {
+  const p = configPath(projectRoot);
+  if (!fs.existsSync(p)) return null;
+  try {
+    return JSON.parse(fs.readFileSync(p, "utf-8"));
+  } catch {
+    return null;
+  }
+}
+
+function writeConfig(config, projectRoot) {
+  const p = configPath(projectRoot);
+  fs.writeFileSync(p, JSON.stringify(config, null, 2) + "\n", "utf-8");
+}
+
+function getEntryPoint(projectRoot) {
+  const config = readConfig(projectRoot);
+  return config && config.entryPoint ? config.entryPoint : null;
+}
+
+module.exports = { readConfig, writeConfig, getEntryPoint, CONFIG_FILE };

package/lib/detect.js

@@ -1,6 +1,6 @@
 /**
  * Detect existing AI instruction files in the project root.
- * Returns an array of { tool, file, path } objects.
+ * Returns an array of { tool, file, fullPath, isDir } objects.
  */
 
 const fs = require("fs");
@@ -15,25 +15,60 @@ const INSTRUCTION_FILES = [
   { tool: "Windsurf", file: ".windsurf/rules" },
   { tool: "Cline", file: ".clinerules" },
   { tool: "Codex / Gemini", file: "AGENTS.md" },
+  { tool: "Antigravity", file: ".antigravity/rules.md" },
+  { tool: "Gemini CLI", file: ".gemini/GEMINI.md" },
   { tool: "Aider", file: "CONVENTIONS.md" },
 ];
 
+/**
+ * Find AGENTS.md case-insensitively in projectRoot.
+ * Returns the actual filename (e.g. "agents.md", "Agents.md") or null.
+ */
+function findAgentsMdCaseInsensitive(projectRoot) {
+  try {
+    const entries = fs.readdirSync(projectRoot);
+    const match = entries.find(
+      (e) => e.toLowerCase() === "agents.md" && fs.statSync(path.join(projectRoot, e)).isFile()
+    );
+    return match || null;
+  } catch {
+    return null;
+  }
+}
+
 function detectInstructionFiles(projectRoot) {
   const found = [];
+  const seenLower = new Set();
+
   for (const entry of INSTRUCTION_FILES) {
+    // Skip AGENTS.md in the static list — handled by case-insensitive scan
+    if (entry.file.toLowerCase() === "agents.md") continue;
+
     const fullPath = path.join(projectRoot, entry.file);
     if (fs.existsSync(fullPath)) {
       const stat = fs.statSync(fullPath);
-      // For directories (.cursor/rules, .windsurf/rules), note it but don't inject
       found.push({
         tool: entry.tool,
         file: entry.file,
         fullPath,
         isDir: stat.isDirectory(),
       });
+      seenLower.add(entry.file.toLowerCase());
     }
   }
+
+  // Case-insensitive AGENTS.md detection
+  const agentsFile = findAgentsMdCaseInsensitive(projectRoot);
+  if (agentsFile && !seenLower.has(agentsFile.toLowerCase())) {
+    found.push({
+      tool: "Codex / Gemini",
+      file: agentsFile,
+      fullPath: path.join(projectRoot, agentsFile),
+      isDir: false,
+    });
+  }
+
   return found;
 }
 
-module.exports = { detectInstructionFiles, INSTRUCTION_FILES };
+module.exports = { detectInstructionFiles, findAgentsMdCaseInsensitive, INSTRUCTION_FILES };

package/lib/init.js

@@ -2,17 +2,20 @@
  * openclew init — set up openclew in the current project.
  *
  * 1. Create doc/ and doc/log/
- * 2. Detect existing instruction files
- * 3. Propose to inject openclew block
+ * 2. Detect entry point (AGENTS.md case-insensitive by default)
+ * 3. Inject openclew block into entry point
  * 4. Install pre-commit hook for index generation
- * 5. Generate initial _INDEX.md
+ * 5. Create guide + example docs
+ * 6. Generate initial _INDEX.md
  */
 
 const fs = require("fs");
 const path = require("path");
 const readline = require("readline");
-const { detectInstructionFiles } = require("./detect");
+const { detectInstructionFiles, findAgentsMdCaseInsensitive } = require("./detect");
 const { inject, isAlreadyInjected } = require("./inject");
+const { writeConfig } = require("./config");
+const { guideContent, exampleLivingDocContent, exampleLogContent, today } = require("./templates");
 
 const PROJECT_ROOT = process.cwd();
 const DOC_DIR = path.join(PROJECT_ROOT, "doc");
@@ -31,17 +34,15 @@ function ask(question) {
   return new Promise((resolve) => {
     rl.question(question, (answer) => {
       rl.close();
-      resolve(answer.trim().toLowerCase());
+      resolve(answer.trim());
     });
   });
 }
 
 function createDirs() {
-  let created = false;
   if (!fs.existsSync(DOC_DIR)) {
     fs.mkdirSync(DOC_DIR, { recursive: true });
     console.log("  Created doc/");
-    created = true;
   } else {
     console.log("  doc/ already exists");
   }
@@ -49,12 +50,68 @@ function createDirs() {
   if (!fs.existsSync(LOG_DIR)) {
     fs.mkdirSync(LOG_DIR, { recursive: true });
     console.log("  Created doc/log/");
-    created = true;
   } else {
     console.log("  doc/log/ already exists");
   }
+}
+
+/**
+ * Resolve the entry point file.
+ *
+ * Priority:
+ * 1. AGENTS.md (case-insensitive) — default, universal
+ * 2. Other detected instruction files — user picks one
+ * 3. Create AGENTS.md — if nothing exists
+ */
+async function resolveEntryPoint() {
+  if (noInject) {
+    console.log("  Skipping entry point setup (--no-inject)");
+    return null;
+  }
+
+  // 1. Check for AGENTS.md (case-insensitive)
+  const agentsFile = findAgentsMdCaseInsensitive(PROJECT_ROOT);
+  if (agentsFile) {
+    if (!process.stdin.isTTY) {
+      // Non-interactive: accept AGENTS.md by default
+      console.log(`  Using ${agentsFile} (non-interactive)`);
+      return { file: agentsFile, fullPath: path.join(PROJECT_ROOT, agentsFile), created: false };
+    }
+    const answer = await ask(`  Found ${agentsFile} — use as entry point? [Y/n] `);
+    if (answer === "" || answer.toLowerCase() === "y" || answer.toLowerCase() === "yes") {
+      return { file: agentsFile, fullPath: path.join(PROJECT_ROOT, agentsFile), created: false };
+    }
+  }
+
+  // 2. Detect other instruction files
+  const others = detectInstructionFiles(PROJECT_ROOT).filter(
+    (f) => !f.isDir && f.file.toLowerCase() !== "agents.md"
+  );
+
+  if (others.length > 0) {
+    console.log("  Detected instruction files:");
+    others.forEach((f, i) => console.log(`    ${i + 1}. ${f.file} (${f.tool})`));
+    console.log(`    ${others.length + 1}. Create new AGENTS.md`);
+
+    if (!process.stdin.isTTY) {
+      // Non-interactive: default to first detected file
+      console.log(`  Using ${others[0].file} (non-interactive)`);
+      return { file: others[0].file, fullPath: others[0].fullPath, created: false };
+    }
+
+    const choice = await ask(`  Choose entry point [1-${others.length + 1}]: `);
+    const idx = parseInt(choice, 10) - 1;
+
+    if (idx >= 0 && idx < others.length) {
+      return { file: others[idx].file, fullPath: others[idx].fullPath, created: false };
+    }
+  }
 
-  return created;
+  // 3. Create AGENTS.md
+  const agentsPath = path.join(PROJECT_ROOT, "AGENTS.md");
+  fs.writeFileSync(agentsPath, `# ${path.basename(PROJECT_ROOT)}\n\nProject instructions for AI agents.\n`, "utf-8");
+  console.log("  Created AGENTS.md");
+  return { file: "AGENTS.md", fullPath: agentsPath, created: true };
 }
 
 function installPreCommitHook() {
@@ -69,21 +126,10 @@ function installPreCommitHook() {
   }
 
   const preCommitPath = path.join(hooksDir, "pre-commit");
-  const indexScript = `python3 -c "
-import subprocess, sys
-try:
-    from pathlib import Path
-    # Try local hook first, then npx-installed
-    local = Path('hooks/generate-index.py')
-    if local.exists():
-        exec(local.read_text())
-    else:
-        # Fallback: run via npx
-        subprocess.run([sys.executable, '-c', 'from openclew import generate_index; generate_index()'], check=True)
-except Exception as e:
-    print(f'openclew index generation skipped: {e}')
-" 2>/dev/null
-git add doc/_INDEX.md 2>/dev/null`;
+  const indexScript = `if [ -f doc/generate-index.py ]; then
+  python3 doc/generate-index.py doc 2>/dev/null || echo "openclew: index generation failed"
+  git add doc/_INDEX.md 2>/dev/null
+fi`;
 
   const MARKER = "# openclew-index";
 
@@ -93,19 +139,10 @@ git add doc/_INDEX.md 2>/dev/null`;
       console.log("  Pre-commit hook already contains openclew index generation");
       return false;
     }
-    // Append to existing hook
-    fs.appendFileSync(
-      preCommitPath,
-      `\n\n${MARKER}\n${indexScript}\n`,
-      "utf-8"
-    );
+    fs.appendFileSync(preCommitPath, `\n\n${MARKER}\n${indexScript}\n`, "utf-8");
     console.log("  Appended openclew index generation to existing pre-commit hook");
   } else {
-    fs.writeFileSync(
-      preCommitPath,
-      `#!/bin/sh\n\n${MARKER}\n${indexScript}\n`,
-      "utf-8"
-    );
+    fs.writeFileSync(preCommitPath, `#!/bin/sh\n\n${MARKER}\n${indexScript}\n`, "utf-8");
     fs.chmodSync(preCommitPath, "755");
     console.log("  Created pre-commit hook for index generation");
   }
@@ -132,6 +169,35 @@ function copyGenerateIndex() {
   return false;
 }
 
+function createDocs() {
+  // Guide — always created
+  const guidePath = path.join(DOC_DIR, "_USING_OPENCLEW.md");
+  if (!fs.existsSync(guidePath)) {
+    fs.writeFileSync(guidePath, guideContent(), "utf-8");
+    console.log("  Created doc/_USING_OPENCLEW.md (guide)");
+  } else {
+    console.log("  doc/_USING_OPENCLEW.md already exists");
+  }
+
+  // Example living doc
+  const examplePath = path.join(DOC_DIR, "_ARCHITECTURE.md");
+  if (!fs.existsSync(examplePath)) {
+    fs.writeFileSync(examplePath, exampleLivingDocContent(), "utf-8");
+    console.log("  Created doc/_ARCHITECTURE.md (example living doc)");
+  } else {
+    console.log("  doc/_ARCHITECTURE.md already exists");
+  }
+
+  // Example log
+  const logPath = path.join(LOG_DIR, `${today()}_setup-openclew.md`);
+  if (!fs.existsSync(logPath)) {
+    fs.writeFileSync(logPath, exampleLogContent(), "utf-8");
+    console.log(`  Created doc/log/${today()}_setup-openclew.md (example log)`);
+  } else {
+    console.log(`  doc/log/${today()}_setup-openclew.md already exists`);
+  }
+}
+
 function runIndexGenerator() {
   const indexScript = path.join(DOC_DIR, "generate-index.py");
   if (!fs.existsSync(indexScript)) return;
@@ -156,38 +222,23 @@ async function main() {
   console.log("\n2. Index generator");
   copyGenerateIndex();
 
-  // Step 3: Detect and inject into instruction files
-  console.log("\n3. Instruction files");
-  const found = detectInstructionFiles(PROJECT_ROOT);
+  // Step 3: Entry point
+  console.log("\n3. Entry point");
+  const entryPoint = await resolveEntryPoint();
 
-  if (found.length === 0) {
-    console.log("  No instruction file detected (CLAUDE.md, .cursorrules, AGENTS.md...)");
-    console.log("  You can manually add the openclew block later. See: openclew help");
-  } else if (noInject) {
-    console.log("  Detected:", found.map((f) => f.file).join(", "));
-    console.log("  Skipping injection (--no-inject)");
-  } else {
-    for (const entry of found) {
-      if (entry.isDir) {
-        console.log(`  Found ${entry.file}/ (directory) — manual setup needed`);
-        continue;
-      }
-
-      if (isAlreadyInjected(entry.fullPath)) {
-        console.log(`  ${entry.file} already has openclew block`);
-        continue;
-      }
-
-      const answer = await ask(
-        `  Inject openclew block into ${entry.file}? [Y/n] `
-      );
-      if (answer === "" || answer === "y" || answer === "yes") {
-        inject(entry.fullPath);
-        console.log(`  Injected into ${entry.file}`);
-      } else {
-        console.log(`  Skipped ${entry.file}`);
-      }
+  if (entryPoint) {
+    if (isAlreadyInjected(entryPoint.fullPath)) {
+      console.log(`  ${entryPoint.file} already has openclew block`);
+    } else {
+      inject(entryPoint.fullPath);
+      console.log(`  Injected openclew block into ${entryPoint.file}`);
     }
+
+    writeConfig({ entryPoint: entryPoint.file }, PROJECT_ROOT);
+    console.log(`  Saved entry point → .openclew.json`);
+  } else {
+    // --no-inject: still create config to mark init was done
+    writeConfig({ entryPoint: null }, PROJECT_ROOT);
   }
 
   // Step 4: Pre-commit hook
@@ -198,14 +249,24 @@ async function main() {
     installPreCommitHook();
   }
 
-  // Step 5: Generate initial index
-  console.log("\n5. Index");
+  // Step 5: Docs
+  console.log("\n5. Docs");
+  createDocs();
+
+  // Step 6: Generate index
+  console.log("\n6. Index");
   runIndexGenerator();
 
   // Done
-  console.log("\nDone. Next steps:");
-  console.log("  openclew new \"Architecture decisions\"   — create your first doc");
-  console.log("  openclew log \"Setup auth\"               — create a session log");
+  console.log("\n─── Ready ───\n");
+  if (entryPoint) {
+    console.log(`  Entry point: ${entryPoint.file}`);
+  }
+  console.log("  Guide:       doc/_USING_OPENCLEW.md");
+  console.log("");
+  console.log("  Start a session with your agent now.");
+  console.log('  Ask it: "Read doc/_USING_OPENCLEW.md and document our architecture."');
+  console.log("  That's it — openclew works from here.");
   console.log("");
 }
 

package/lib/inject.js

@@ -7,13 +7,17 @@ const fs = require("fs");
 const OPENCLEW_BLOCK = `
 ## Project knowledge (openclew)
 
-Structured documentation lives in \`doc/\`. Each doc has 3 levels (L1/L2/L3).
+This file is the **entry point** for project documentation.
 
-**Before any task:** read \`doc/_INDEX.md\`, identify docs related to the task, read them.
+**Doc-first rule:** before any task, read \`doc/_INDEX.md\` to find docs related to the task. Read them before exploring code.
 
-- Permanent docs: \`doc/_*.md\` — living knowledge (architecture, conventions, decisions)
-- Logs: \`doc/log/YYYY-MM-DD_*.md\` — frozen facts (what happened, never modified)
-- Read L1 first to decide if you need L2/L3
+Two types of docs in \`doc/\`:
+- **Living docs** (\`doc/_*.md\`) — evolve with the project (architecture, conventions, decisions)
+- **Logs** (\`doc/log/YYYY-MM-DD_*.md\`) — frozen facts from a session, never modified after
+
+Each doc has 3 levels: **L1** (metadata — read first to decide relevance) → **L2** (summary) → **L3** (full details, only when needed).
+
+**Creating docs:** when a decision, convention, or significant event needs to be captured, create the file directly following the format in \`doc/_USING_OPENCLEW.md\`.
 `.trim();
 
 const MARKER_START = "<!-- openclew_START -->";

package/lib/new-doc.js

@@ -1,10 +1,11 @@
 /**
- * openclew new <title> — create a new permanent doc.
+ * openclew new <title> — create a new living doc.
  */
 
 const fs = require("fs");
 const path = require("path");
-const { permanentContent, slugify } = require("./templates");
+const { livingContent, slugify } = require("./templates");
+const { readConfig } = require("./config");
 
 const args = process.argv.slice(2);
 // Remove "new" command from args
@@ -17,11 +18,15 @@ if (!title) {
   process.exit(1);
 }
 
-const docDir = path.join(process.cwd(), "doc");
+const projectRoot = process.cwd();
+const docDir = path.join(projectRoot, "doc");
 if (!fs.existsSync(docDir)) {
   console.error("No doc/ directory found. Run 'openclew init' first.");
   process.exit(1);
 }
+if (!readConfig(projectRoot)) {
+  console.warn("Warning: no .openclew.json found. Run 'openclew init' first.");
+}
 
 const slug = slugify(title);
 const filename = `_${slug}.md`;
@@ -32,5 +37,10 @@ if (fs.existsSync(filepath)) {
   process.exit(1);
 }
 
-fs.writeFileSync(filepath, permanentContent(title), "utf-8");
+fs.writeFileSync(filepath, livingContent(title), "utf-8");
 console.log(`Created doc/${filename}`);
+console.log("");
+console.log("Next: open the file and fill in:");
+console.log("  L1 — subject, status, keywords (so the index can find it)");
+console.log("  L2 — objective + key points (what agents and humans need to know)");
+console.log("  L3 — full details (only when needed)");

package/lib/new-log.js

@@ -5,6 +5,7 @@
 const fs = require("fs");
 const path = require("path");
 const { logContent, slugifyLog, today } = require("./templates");
+const { readConfig } = require("./config");
 
 const args = process.argv.slice(2);
 // Remove "log" command from args
@@ -17,11 +18,15 @@ if (!title) {
   process.exit(1);
 }
 
-const logDir = path.join(process.cwd(), "doc", "log");
+const projectRoot = process.cwd();
+const logDir = path.join(projectRoot, "doc", "log");
 if (!fs.existsSync(logDir)) {
   console.error("No doc/log/ directory found. Run 'openclew init' first.");
   process.exit(1);
 }
+if (!readConfig(projectRoot)) {
+  console.warn("Warning: no .openclew.json found. Run 'openclew init' first.");
+}
 
 const slug = slugifyLog(title);
 const date = today();
@@ -35,3 +40,9 @@ if (fs.existsSync(filepath)) {
 
 fs.writeFileSync(filepath, logContent(title), "utf-8");
 console.log(`Created doc/log/${filename}`);
+console.log("");
+console.log("Next: open the file and fill in:");
+console.log("  L1 — type, status, short_story (what happened in 1-2 sentences)");
+console.log("  L2 — problem + solution (the facts, frozen after this session)");
+console.log("");
+console.log("Logs are immutable — once written, never modified.");

package/lib/templates.js

@@ -1,5 +1,5 @@
 /**
- * Template content for permanent docs and logs.
+ * Template content for living docs and logs.
  * Embedded here so the CLI works standalone without needing to locate template files.
  */
 
@@ -21,7 +21,7 @@ function slugifyLog(title) {
     .replace(/^-|-$/g, "");
 }
 
-function permanentContent(title) {
+function livingContent(title) {
   const date = today();
   return `<!-- L1_START -->
 # L1 - Metadata
@@ -103,4 +103,266 @@ keywords: []
 `;
 }
 
-module.exports = { permanentContent, logContent, slugify, slugifyLog, today };
+/**
+ * Guide doc — always created by init.
+ * This is what agents read to understand openclew.
+ */
+function guideContent() {
+  const date = today();
+  return `<!-- L1_START -->
+# L1 - Metadata
+type: Guide
+subject: How openclew works
+created: ${date}
+updated: ${date}
+short_story: How openclew structures project knowledge in 3 levels (L1/L2/L3) so AI agents and humans navigate efficiently.
+status: Active
+category: Documentation
+keywords: [openclew, L1, L2, L3, index, living-doc, log]
+<!-- L1_END -->
+
+---
+
+<!-- L2_START -->
+# L2 - Summary
+
+## What is openclew?
+
+openclew gives your project a structured memory that both humans and AI agents can navigate efficiently.
+
+## Doc-first rule
+
+Before starting any task, read \`doc/_INDEX.md\` to find docs related to the task. Read them before exploring code. This avoids reinventing what's already documented.
+
+## Two types of docs
+
+**Living docs** (\`doc/_*.md\`): knowledge that evolves with the project.
+Architecture decisions, conventions, known pitfalls — anything that stays relevant over time.
+Naming: \`doc/_UPPER_SNAKE_CASE.md\` (e.g. \`doc/_AUTH_DESIGN.md\`)
+
+**Logs** (\`doc/log/YYYY-MM-DD_*.md\`): frozen facts from a work session.
+What happened, what was decided, what was tried. Never modified after the session.
+Naming: \`doc/log/YYYY-MM-DD_lowercase-slug.md\` (e.g. \`doc/log/2026-01-15_setup-auth.md\`)
+
+## Three levels per doc
+
+Every doc has 3 levels. Read only what you need:
+
+- **L1 — Metadata** (~40 tokens): subject, keywords, status. Read this first to decide if the doc is relevant.
+- **L2 — Summary**: the essential context — objective, key points, decisions.
+- **L3 — Details**: full technical content. Only read when deep-diving.
+
+## Index
+
+\`doc/_INDEX.md\` is auto-generated from L1 metadata on every git commit (via a pre-commit hook).
+Never edit it manually. To force a rebuild: \`openclew index\`
+<!-- L2_END -->
+
+---
+
+<!-- L3_START -->
+# L3 - Details
+
+## Creating a living doc
+
+Create \`doc/_TITLE.md\` (uppercase snake_case) with this structure:
+
+\`\`\`
+<!-- L1_START -->
+# L1 - Metadata
+type: Reference
+subject: Title
+created: YYYY-MM-DD
+updated: YYYY-MM-DD
+short_story:
+status: Active
+category:
+keywords: []
+<!-- L1_END -->
+
+---
+
+<!-- L2_START -->
+# L2 - Summary
+## Objective
+## Key points
+<!-- L2_END -->
+
+---
+
+<!-- L3_START -->
+# L3 - Details
+<!-- L3_END -->
+\`\`\`
+
+**When to create one:**
+- A decision was made that others need to know (architecture, convention, API design)
+- A pattern or pitfall keeps coming up
+- You want an agent to know something at the start of every session
+
+## Creating a log
+
+Create \`doc/log/YYYY-MM-DD_slug.md\` (lowercase, hyphens) with this structure:
+
+\`\`\`
+<!-- L1_START -->
+# L1 - Metadata
+date: YYYY-MM-DD
+type: Feature
+subject: Title
+short_story:
+status: In progress
+category:
+keywords: []
+<!-- L1_END -->
+
+---
+
+<!-- L2_START -->
+# L2 - Summary
+## Objective
+## Problem
+## Solution
+<!-- L2_END -->
+
+---
+
+<!-- L3_START -->
+# L3 - Details
+<!-- L3_END -->
+\`\`\`
+
+**When to create one:**
+- End of a work session (what was done, what's left)
+- A bug was investigated and resolved
+- A spike or experiment was conducted
+
+Logs are immutable — once the session ends, the log is never modified.
+
+## How agents should use this
+
+1. At session start: read the entry point file
+2. Before any task: read \`doc/_INDEX.md\`, scan L1 metadata, identify relevant docs
+3. Read L2 of relevant docs for context
+4. Only read L3 when you need implementation details
+5. After significant work: create or update living docs and logs directly
+
+The index (\`doc/_INDEX.md\`) auto-regenerates on every git commit. To force a rebuild: \`openclew index\`
+
+---
+
+## Changelog
+
+| Date | Change |
+|------|--------|
+| ${date} | Created by openclew init |
+<!-- L3_END -->
+`;
+}
+
+/**
+ * Example living doc — shows what a filled-in doc looks like.
+ */
+function exampleLivingDocContent() {
+  const date = today();
+  return `<!-- L1_START -->
+# L1 - Metadata
+type: Reference
+subject: Architecture overview
+created: ${date}
+updated: ${date}
+short_story: High-level architecture of the project — components, data flow, key decisions.
+status: Active
+category: Architecture
+keywords: [architecture, overview, components]
+<!-- L1_END -->
+
+---
+
+<!-- L2_START -->
+# L2 - Summary
+
+## Objective
+Document the high-level architecture so new contributors and AI agents understand the system quickly.
+
+## Key points
+- Replace this with your actual architecture
+- Describe the main components and how they interact
+- Note key technical decisions and their rationale
+<!-- L2_END -->
+
+---
+
+<!-- L3_START -->
+# L3 - Details
+
+<!-- Replace this with your actual architecture details -->
+
+This is an example living doc created by \`openclew init\`.
+Edit it to document your project's architecture, or delete it and create your own.
+
+---
+
+## Changelog
+
+| Date | Change |
+|------|--------|
+| ${date} | Created by openclew init (example) |
+<!-- L3_END -->
+`;
+}
+
+/**
+ * Example log — shows what a filled-in log looks like.
+ */
+function exampleLogContent() {
+  const date = today();
+  return `<!-- L1_START -->
+# L1 - Metadata
+date: ${date}
+type: Feature
+subject: Set up openclew
+short_story: Initialized openclew for structured project knowledge. Created doc/ structure, git hook, guide, and example docs.
+status: Done
+category: Tooling
+keywords: [openclew, setup, documentation]
+<!-- L1_END -->
+
+---
+
+<!-- L2_START -->
+# L2 - Summary
+
+## Objective
+Set up structured documentation so AI agents and new contributors can navigate project knowledge efficiently.
+
+## Problem
+Project knowledge was scattered — README, inline comments, tribal knowledge. Each new AI session started from zero.
+
+## Solution
+Installed openclew. Every doc now has L1 (metadata for triage), L2 (summary for context), L3 (details when needed).
+The index auto-regenerates on each commit via a git hook.
+<!-- L2_END -->
+
+---
+
+<!-- L3_START -->
+# L3 - Details
+
+This log was created by \`openclew init\`.
+It shows what a filled-in log looks like. Logs are immutable — once the session ends, the log is frozen.
+For evolving knowledge, use living docs (\`doc/_*.md\`).
+<!-- L3_END -->
+`;
+}
+
+module.exports = {
+  livingContent,
+  logContent,
+  guideContent,
+  exampleLivingDocContent,
+  exampleLogContent,
+  slugify,
+  slugifyLog,
+  today,
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openclew",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Long Life Memory for LLMs — structured project knowledge for AI agents and humans",
   "license": "MIT",
   "bin": {