openclew 0.0.1 → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 R.AlphA
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,299 @@
+# openclew
+
+> Long Life Memory for LLMs
+
+**Your agent forgets. Your project remembers.**
+
+In Greek mythology, Ariadne gave Theseus a *clew* — a ball of thread — to find his way out of the Minotaur's labyrinth. That thread is the etymological origin of the word "clue." It wasn't a map. It wasn't a search engine. It was a continuous trail that connected where you've been to where you are.
+
+That's what openclew does for your project. Every decision, every architectural choice, every hard-won lesson — laid down as a thread that any reader (human or AI) can follow. Not scattered across wikis, chat logs, and CLAUDE.md files that grow until they're unreadable. One trail. One source of truth.
+
+---
+
+## Why this exists
+
+AI agents are powerful, but they're amnesiac. Every new session starts from zero. The usual fixes don't work:
+
+| Approach | What goes wrong |
+|----------|----------------|
+| CLAUDE.md / .cursorrules | Grows into an unreadable wall of text. Agent loads everything, wastes tokens on irrelevant context |
+| Agent memory (Claude, Copilot) | Opaque, not versioned, not shareable with the team |
+| Wiki / Notion | Disconnected from the code, goes stale |
+| README.md | Not structured for AI consumption |
+| Nothing | Re-explain everything every session |
+
+The deeper problem isn't *storage* — it's **navigation**. A project with 50 documents and 200K tokens of knowledge can't be loaded in full. The real question an agent (or a human) needs to answer is:
+
+> **"Should I read this document?"**
+
+Not "does this file contain the word `auth`?" — that's pattern matching. The question is about *relevance*. And you can only answer it if documents are designed to be skimmed before they're read.
+
+---
+
+## The idea: 3 levels of depth
+
+Every openclew document has 3 levels. Same file, different depths — for different needs.
+
+```
+┌─────────────────────────────────────────────┐
+│  L1 — Metadata                              │
+│  type, subject, status, keywords            │
+│  → "Should I read this?" — decidable in     │
+│     2 seconds, ~40 tokens per doc            │
+│  → Auto-indexed, machine-parseable          │
+├─────────────────────────────────────────────┤
+│  L2 — Summary                               │
+│  Objective, key points, solution            │
+│  → The full picture in 30 seconds           │
+│  → Enough for most decisions                │
+├─────────────────────────────────────────────┤
+│  L3 — Details                               │
+│  Code, examples, history, edge cases        │
+│  → Deep-dive only when actually needed      │
+│  → Most readers never go here               │
+└─────────────────────────────────────────────┘
+```
+
+This isn't just an organizational trick — it's a **token efficiency strategy**. A project with 50 docs:
+
+| Strategy | Tokens consumed | Relevance |
+|----------|----------------|-----------|
+| Load everything | ~200K | Mostly noise |
+| Grep for keywords | Variable | Misses context, false positives |
+| **Read all L1s, then L2 of relevant docs** | **~2K + 2-3 docs** | **Precise, contextual** |
+
+L1 answers "should I read this?" L2 answers "what do I need to know?" L3 is there when you need the details. Most of the time, you don't.
+
+---
+
+## Two types of docs
+
+| Type | Location | Role | Mutability |
+|------|----------|------|------------|
+| **Permanent** | `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.
+**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.
+
+---
+
+## Quick start (5 minutes)
+
+### 1. Create the structure
+
+```bash
+mkdir -p doc/log
+```
+
+### 2. Copy the templates
+
+Download from [`templates/`](templates/) or create manually:
+
+<details>
+<summary><b>templates/permanent.md</b> — for living knowledge</summary>
+
+```markdown
+<!-- L1_START -->
+# L1 - Metadata
+type: Reference | Architecture | Guide | Analysis
+subject: Short title (< 60 chars)
+created: YYYY-MM-DD
+updated: YYYY-MM-DD
+short_story: 1-2 sentences. What this doc covers and what it concludes.
+status: Active | Stable | Archived
+category: Main domain (e.g. Auth, API, Database, UI...)
+keywords: [tag1, tag2, tag3]
+<!-- L1_END -->
+
+---
+
+<!-- L2_START -->
+# L2 - Summary
+
+## Objective
+<!-- Why this document exists -->
+
+## Key points
+<!-- 3-5 essential takeaways -->
+
+## Solution
+<!-- Recommended approach or pattern -->
+<!-- L2_END -->
+
+---
+
+<!-- L3_START -->
+# L3 - Details
+
+<!-- Full technical content: examples, code, references... -->
+
+## Changelog
+
+| Date | Change |
+|------|--------|
+| YYYY-MM-DD | Initial creation |
+<!-- L3_END -->
+```
+
+</details>
+
+<details>
+<summary><b>templates/log.md</b> — for frozen facts</summary>
+
+```markdown
+<!-- L1_START -->
+# L1 - Metadata
+date: YYYY-MM-DD
+type: Bug | Feature | Refactor | Doc | Deploy
+subject: Short title (< 60 chars)
+short_story: 1-2 sentences. What happened and what was the outcome.
+status: Done | In progress | Abandoned
+category: Main domain
+keywords: [tag1, tag2, tag3]
+<!-- L1_END -->
+
+---
+
+<!-- L2_START -->
+# L2 - Summary
+
+## Problem
+<!-- What was observed -->
+
+## Solution
+<!-- How it was resolved -->
+<!-- L2_END -->
+
+---
+
+<!-- L3_START -->
+# L3 - Details
+
+<!-- Technical details: code changes, debugging steps, references... -->
+<!-- L3_END -->
+```
+
+</details>
+
+### 3. Write your first doc
+
+```bash
+cp templates/permanent.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.
+
+### 4. Point your agent to it
+
+Add this to your `CLAUDE.md`, `.cursorrules`, or `AGENTS.md`:
+
+```markdown
+## Project knowledge
+
+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)
+- Logs: `doc/log/YYYY-MM-DD_*.md` (frozen facts, never modified)
+- Index: `doc/_INDEX.md` (auto-generated, start here)
+```
+
+### 5. Auto-generate the index (optional)
+
+Copy [`hooks/generate-index.py`](hooks/generate-index.py) to your project and add it as a pre-commit hook:
+
+```bash
+# Option A: git hook
+cp hooks/generate-index.py .git/hooks/generate-index.py
+echo 'python .git/hooks/generate-index.py && git add doc/_INDEX.md' >> .git/hooks/pre-commit
+chmod +x .git/hooks/pre-commit
+
+# Option B: pre-commit framework
+# See hooks/README.md for .pre-commit-config.yaml setup
+```
+
+The index auto-regenerates on every commit. Never edit it manually.
+
+---
+
+## How it works in practice
+
+**Session 1** — You're setting up auth:
+```
+doc/
+├── _ARCHITECTURE.md          # Your stack, main patterns
+└── log/
+    └── 2026-03-07_setup-auth.md   # What you did, decisions made
+```
+
+**Session 5** — New agent session, different feature:
+```
+Agent reads doc/_INDEX.md (auto-generated)
+  → Scans all L1s: "Should I read this?"
+  → _ARCHITECTURE.md → yes → reads L2
+  → setup-auth log → relevant → reads L2
+  → Skips the rest
+  → Full context in ~1K tokens instead of 50K
+```
+
+**Session 20** — Your project has grown:
+```
+doc/
+├── _INDEX.md                      # Auto-generated, 30 entries
+├── _ARCHITECTURE.md               # Updated 12 times
+├── _AUTH.md                       # Extracted when auth got complex
+├── _API_CONVENTIONS.md            # Team conventions
+├── _KNOWN_ISSUES.md               # Active gotchas
+└── log/
+    ├── 2026-03-07_setup-auth.md
+    ├── 2026-03-10_migrate-db.md
+    ├── 2026-03-15_fix-token-refresh.md
+    └── ... (20 more)
+```
+
+30 docs. The agent scans all L1s in 2 seconds, reads the 3 that matter, and starts working with full context. A new teammate does the same — reads L2s to get up to speed in minutes. Same docs, same truth, different depth.
+
+---
+
+## Principles
+
+- **"Should I read this?"** — L1 exists to answer this question. If it can't, the L1 is poorly written.
+- **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.
+- **Index is auto-generated** — Never edit `_INDEX.md` manually.
+
+---
+
+## Works with everything
+
+**AI agents:** Claude Code, Cursor, Copilot, Windsurf, Codex, Zed, Kiro, Aider, Cline, Gemini CLI...
+
+**Workflow frameworks:** BMAD, Spec Kit, or any methodology — openclew handles knowledge, your framework handles process.
+
+**It's just Markdown.** No runtime, no dependencies, no lock-in. Git-versioned, diffable, reviewable in PRs. If you stop using it, the docs are still useful — to humans and agents alike.
+
+---
+
+## Compared to alternatives
+
+| Feature | CLAUDE.md | Cline Memory Bank | BMAD | openclew |
+|---------|-----------|-------------------|------|----------|
+| Readable by humans AND agents | partial | partial | yes | **yes** |
+| Levels of depth (L1/L2/L3) | - | - | - | **yes** |
+| "Should I read this?" (L1 triage) | - | - | - | **yes** |
+| Token-efficient navigation | - | - | partial | **yes** |
+| Auto-generated index | - | - | CSV | **yes** |
+| Immutable logs | - | - | - | **yes** |
+| Git-versioned | yes | yes | yes | **yes** |
+| Cross-project | - | - | - | **yes** |
+| Tool-agnostic | Claude only | Cline only | multi | **yes** |
+
+---
+
+## License
+
+MIT — use it however you want.

package/bin/openclew.js

@@ -0,0 +1,41 @@
+#!/usr/bin/env node
+
+const { resolve } = require("path");
+
+const args = process.argv.slice(2);
+const command = args[0];
+
+const USAGE = `
+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 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)
+`.trim();
+
+if (!command || command === "help" || command === "--help" || command === "-h") {
+  console.log(USAGE);
+  process.exit(0);
+}
+
+const commands = {
+  init: () => require("../lib/init"),
+  new: () => require("../lib/new-doc"),
+  log: () => require("../lib/new-log"),
+  index: () => require("../lib/index-gen"),
+};
+
+if (!commands[command]) {
+  console.error(`Unknown command: ${command}`);
+  console.error(`Run 'openclew help' for usage.`);
+  process.exit(1);
+}
+
+commands[command]();

package/hooks/generate-index.py

@@ -0,0 +1,157 @@
+#!/usr/bin/env python3
+"""
+openclew index generator.
+
+Scans doc/_*.md (permanents) and doc/log/*.md (logs),
+parses L1 metadata blocks, and generates doc/_INDEX.md.
+
+Usage:
+    python generate-index.py              # from project root
+    python generate-index.py /path/to/doc # custom doc directory
+
+Idempotent: running twice produces the same output.
+Zero dependencies: Python 3.8+ standard library only.
+"""
+
+import os
+import re
+import sys
+from datetime import datetime
+from pathlib import Path
+
+
+def find_doc_dir():
+    """Find the doc/ directory."""
+    if len(sys.argv) > 1:
+        doc_dir = Path(sys.argv[1])
+    else:
+        doc_dir = Path("doc")
+
+    if not doc_dir.is_dir():
+        print(f"No '{doc_dir}' directory found. Nothing to index.")
+        sys.exit(0)
+
+    return doc_dir
+
+
+def parse_l1(filepath):
+    """Extract L1 metadata from a file."""
+    try:
+        content = filepath.read_text(encoding="utf-8")
+    except (OSError, UnicodeDecodeError):
+        return None
+
+    match = re.search(
+        r"<!--\s*L1_START\s*-->(.+?)<!--\s*L1_END\s*-->",
+        content,
+        re.DOTALL,
+    )
+    if not match:
+        return None
+
+    block = match.group(1)
+    meta = {}
+    for line in block.splitlines():
+        line = line.strip()
+        if line.startswith("#") or not line:
+            continue
+        if ":" in line:
+            key, _, value = line.partition(":")
+            meta[key.strip().lower()] = value.strip()
+
+    return meta
+
+
+def collect_docs(doc_dir):
+    """Collect permanents and logs with their L1 metadata."""
+    permanents = []
+    logs = []
+
+    # Permanent 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))
+
+    # Log docs: doc/log/*.md
+    log_dir = doc_dir / "log"
+    if log_dir.is_dir():
+        for f in sorted(log_dir.glob("*.md"), reverse=True):
+            meta = parse_l1(f)
+            if meta:
+                logs.append((f, meta))
+
+    return permanents, logs
+
+
+def generate_index(doc_dir, permanents, logs):
+    """Generate _INDEX.md content."""
+    now = datetime.now().strftime("%Y-%m-%d %H:%M")
+    lines = [
+        f"# Project Knowledge Index",
+        f"",
+        f"> Auto-generated by [openclew](https://github.com/openclew/openclew) on {now}.",
+        f"> Do not edit manually — rebuilt from L1 metadata on every commit.",
+        f"",
+    ]
+
+    # Permanents section
+    lines.append("## Permanent docs")
+    lines.append("")
+    if permanents:
+        lines.append("| Document | Subject | Status | Category |")
+        lines.append("|----------|---------|--------|----------|")
+        for f, meta in permanents:
+            name = f.name
+            subject = meta.get("subject", "—")
+            status = meta.get("status", "—")
+            category = meta.get("category", "—")
+            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("")
+
+    # Logs section (last 20)
+    lines.append("## Recent logs")
+    lines.append("")
+    display_logs = logs[:20]
+    if display_logs:
+        lines.append("| Date | Subject | Status | Category |")
+        lines.append("|------|---------|--------|----------|")
+        for f, meta in display_logs:
+            date = meta.get("date", f.stem[:10])
+            subject = meta.get("subject", "—")
+            status = meta.get("status", "—")
+            category = meta.get("category", "—")
+            rel_path = f.relative_to(doc_dir.parent)
+            lines.append(f"| {date} | [{subject}]({rel_path}) | {status} | {category} |")
+        if len(logs) > 20:
+            lines.append(f"")
+            lines.append(f"_{len(logs) - 20} older logs not shown._")
+    else:
+        lines.append("_No logs yet. Create one with `templates/log.md`._")
+    lines.append("")
+
+    # Stats
+    lines.append("---")
+    lines.append(f"**{len(permanents)}** permanent docs, **{len(logs)}** logs.")
+    lines.append("")
+
+    return "\n".join(lines)
+
+
+def main():
+    doc_dir = find_doc_dir()
+    permanents, logs = collect_docs(doc_dir)
+    index_content = generate_index(doc_dir, permanents, 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)")
+
+
+if __name__ == "__main__":
+    main()

package/lib/detect.js

@@ -0,0 +1,39 @@
+/**
+ * Detect existing AI instruction files in the project root.
+ * Returns an array of { tool, file, path } objects.
+ */
+
+const fs = require("fs");
+const path = require("path");
+
+const INSTRUCTION_FILES = [
+  { tool: "Claude Code", file: "CLAUDE.md" },
+  { tool: "Cursor", file: ".cursorrules" },
+  { tool: "Cursor", file: ".cursor/rules" },
+  { tool: "GitHub Copilot", file: ".github/copilot-instructions.md" },
+  { tool: "Windsurf", file: ".windsurfrules" },
+  { tool: "Windsurf", file: ".windsurf/rules" },
+  { tool: "Cline", file: ".clinerules" },
+  { tool: "Codex / Gemini", file: "AGENTS.md" },
+  { tool: "Aider", file: "CONVENTIONS.md" },
+];
+
+function detectInstructionFiles(projectRoot) {
+  const found = [];
+  for (const entry of INSTRUCTION_FILES) {
+    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(),
+      });
+    }
+  }
+  return found;
+}
+
+module.exports = { detectInstructionFiles, INSTRUCTION_FILES };

package/lib/index-gen.js

@@ -0,0 +1,40 @@
+/**
+ * openclew index — regenerate doc/_INDEX.md
+ *
+ * Wraps hooks/generate-index.py. Falls back to a JS implementation
+ * if Python is not available.
+ */
+
+const { execSync } = require("child_process");
+const fs = require("fs");
+const path = require("path");
+
+const docDir = path.join(process.cwd(), "doc");
+
+if (!fs.existsSync(docDir)) {
+  console.error("No doc/ directory found. Run 'openclew init' first.");
+  process.exit(1);
+}
+
+// Try local generate-index.py first
+const localScript = path.join(docDir, "generate-index.py");
+const packageScript = path.join(__dirname, "..", "hooks", "generate-index.py");
+const script = fs.existsSync(localScript) ? localScript : packageScript;
+
+if (fs.existsSync(script)) {
+  try {
+    const output = execSync(`python3 "${script}" "${docDir}"`, {
+      encoding: "utf-8",
+    });
+    console.log(output.trim());
+    process.exit(0);
+  } catch {
+    console.error(
+      "python3 not available. Install Python 3.8+ or regenerate manually."
+    );
+    process.exit(1);
+  }
+}
+
+console.error("generate-index.py not found. Run 'openclew init' first.");
+process.exit(1);

package/lib/init.js

@@ -0,0 +1,212 @@
+/**
+ * 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
+ * 4. Install pre-commit hook for index generation
+ * 5. Generate initial _INDEX.md
+ */
+
+const fs = require("fs");
+const path = require("path");
+const readline = require("readline");
+const { detectInstructionFiles } = require("./detect");
+const { inject, isAlreadyInjected } = require("./inject");
+
+const PROJECT_ROOT = process.cwd();
+const DOC_DIR = path.join(PROJECT_ROOT, "doc");
+const LOG_DIR = path.join(DOC_DIR, "log");
+const GIT_DIR = path.join(PROJECT_ROOT, ".git");
+
+const args = process.argv.slice(2);
+const noHook = args.includes("--no-hook");
+const noInject = args.includes("--no-inject");
+
+function ask(question) {
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout,
+  });
+  return new Promise((resolve) => {
+    rl.question(question, (answer) => {
+      rl.close();
+      resolve(answer.trim().toLowerCase());
+    });
+  });
+}
+
+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");
+  }
+
+  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");
+  }
+
+  return created;
+}
+
+function installPreCommitHook() {
+  if (!fs.existsSync(GIT_DIR)) {
+    console.log("  No .git/ found — skipping hook installation");
+    return false;
+  }
+
+  const hooksDir = path.join(GIT_DIR, "hooks");
+  if (!fs.existsSync(hooksDir)) {
+    fs.mkdirSync(hooksDir, { recursive: true });
+  }
+
+  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 MARKER = "# openclew-index";
+
+  if (fs.existsSync(preCommitPath)) {
+    const existing = fs.readFileSync(preCommitPath, "utf-8");
+    if (existing.includes(MARKER)) {
+      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"
+    );
+    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.chmodSync(preCommitPath, "755");
+    console.log("  Created pre-commit hook for index generation");
+  }
+
+  return true;
+}
+
+function copyGenerateIndex() {
+  const src = path.join(__dirname, "..", "hooks", "generate-index.py");
+  const dst = path.join(DOC_DIR, "generate-index.py");
+
+  if (fs.existsSync(dst)) {
+    console.log("  doc/generate-index.py already exists");
+    return false;
+  }
+
+  if (fs.existsSync(src)) {
+    fs.copyFileSync(src, dst);
+    console.log("  Copied generate-index.py to doc/");
+    return true;
+  }
+
+  console.log("  generate-index.py not found in package — skipping");
+  return false;
+}
+
+function runIndexGenerator() {
+  const indexScript = path.join(DOC_DIR, "generate-index.py");
+  if (!fs.existsSync(indexScript)) return;
+
+  try {
+    const { execSync } = require("child_process");
+    execSync(`python3 "${indexScript}" "${DOC_DIR}"`, { stdio: "pipe" });
+    console.log("  Generated doc/_INDEX.md");
+  } catch {
+    console.log("  Could not generate index (python3 not available)");
+  }
+}
+
+async function main() {
+  console.log("\nopenclew init\n");
+
+  // Step 1: Create directories
+  console.log("1. Project structure");
+  createDirs();
+
+  // Step 2: Copy index generator
+  console.log("\n2. Index generator");
+  copyGenerateIndex();
+
+  // Step 3: Detect and inject into instruction files
+  console.log("\n3. Instruction files");
+  const found = detectInstructionFiles(PROJECT_ROOT);
+
+  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}`);
+      }
+    }
+  }
+
+  // Step 4: Pre-commit hook
+  console.log("\n4. Pre-commit hook");
+  if (noHook) {
+    console.log("  Skipping (--no-hook)");
+  } else {
+    installPreCommitHook();
+  }
+
+  // Step 5: Generate initial index
+  console.log("\n5. 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("");
+}
+
+main();

package/lib/inject.js

@@ -0,0 +1,38 @@
+/**
+ * Inject openclew block into an existing instruction file.
+ */
+
+const fs = require("fs");
+
+const OPENCLEW_BLOCK = `
+## Project knowledge (openclew)
+
+Structured documentation lives in \`doc/\`. Each doc has 3 levels (L1/L2/L3).
+
+**Before any task:** read \`doc/_INDEX.md\`, identify docs related to the task, read them.
+
+- 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
+`.trim();
+
+const MARKER_START = "<!-- openclew_START -->";
+const MARKER_END = "<!-- openclew_END -->";
+
+function isAlreadyInjected(filePath) {
+  const content = fs.readFileSync(filePath, "utf-8");
+  return content.includes(MARKER_START);
+}
+
+function inject(filePath) {
+  if (isAlreadyInjected(filePath)) {
+    return false;
+  }
+
+  const content = fs.readFileSync(filePath, "utf-8");
+  const block = `\n\n${MARKER_START}\n${OPENCLEW_BLOCK}\n${MARKER_END}\n`;
+  fs.writeFileSync(filePath, content + block, "utf-8");
+  return true;
+}
+
+module.exports = { inject, isAlreadyInjected, OPENCLEW_BLOCK, MARKER_START };

package/lib/new-doc.js

@@ -0,0 +1,36 @@
+/**
+ * openclew new <title> — create a new permanent doc.
+ */
+
+const fs = require("fs");
+const path = require("path");
+const { permanentContent, slugify } = require("./templates");
+
+const args = process.argv.slice(2);
+// Remove "new" command from args
+const cmdIndex = args.indexOf("new");
+const titleArgs = cmdIndex >= 0 ? args.slice(cmdIndex + 1) : args.slice(1);
+const title = titleArgs.join(" ");
+
+if (!title) {
+  console.error('Usage: openclew new "Title of the document"');
+  process.exit(1);
+}
+
+const docDir = path.join(process.cwd(), "doc");
+if (!fs.existsSync(docDir)) {
+  console.error("No doc/ directory found. Run 'openclew init' first.");
+  process.exit(1);
+}
+
+const slug = slugify(title);
+const filename = `_${slug}.md`;
+const filepath = path.join(docDir, filename);
+
+if (fs.existsSync(filepath)) {
+  console.error(`File already exists: doc/${filename}`);
+  process.exit(1);
+}
+
+fs.writeFileSync(filepath, permanentContent(title), "utf-8");
+console.log(`Created doc/${filename}`);

package/lib/new-log.js

@@ -0,0 +1,37 @@
+/**
+ * openclew log <title> — create a new session log.
+ */
+
+const fs = require("fs");
+const path = require("path");
+const { logContent, slugifyLog, today } = require("./templates");
+
+const args = process.argv.slice(2);
+// Remove "log" command from args
+const cmdIndex = args.indexOf("log");
+const titleArgs = cmdIndex >= 0 ? args.slice(cmdIndex + 1) : args.slice(1);
+const title = titleArgs.join(" ");
+
+if (!title) {
+  console.error('Usage: openclew log "Title of the log"');
+  process.exit(1);
+}
+
+const logDir = path.join(process.cwd(), "doc", "log");
+if (!fs.existsSync(logDir)) {
+  console.error("No doc/log/ directory found. Run 'openclew init' first.");
+  process.exit(1);
+}
+
+const slug = slugifyLog(title);
+const date = today();
+const filename = `${date}_${slug}.md`;
+const filepath = path.join(logDir, filename);
+
+if (fs.existsSync(filepath)) {
+  console.error(`File already exists: doc/log/${filename}`);
+  process.exit(1);
+}
+
+fs.writeFileSync(filepath, logContent(title), "utf-8");
+console.log(`Created doc/log/${filename}`);

package/lib/templates.js

@@ -0,0 +1,106 @@
+/**
+ * Template content for permanent docs and logs.
+ * Embedded here so the CLI works standalone without needing to locate template files.
+ */
+
+function today() {
+  return new Date().toISOString().slice(0, 10);
+}
+
+function slugify(title) {
+  return title
+    .toUpperCase()
+    .replace(/[^A-Z0-9]+/g, "_")
+    .replace(/^_|_$/g, "");
+}
+
+function slugifyLog(title) {
+  return title
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-|-$/g, "");
+}
+
+function permanentContent(title) {
+  const date = today();
+  return `<!-- L1_START -->
+# L1 - Metadata
+type: Reference
+subject: ${title}
+created: ${date}
+updated: ${date}
+short_story:
+status: Active
+category:
+keywords: []
+<!-- L1_END -->
+
+---
+
+<!-- L2_START -->
+# L2 - Summary
+
+## Objective
+<!-- Why this document exists -->
+
+## Key points
+<!-- 3-5 essential takeaways -->
+<!-- L2_END -->
+
+---
+
+<!-- L3_START -->
+# L3 - Details
+
+<!-- Full technical content -->
+
+---
+
+## Changelog
+
+| Date | Change |
+|------|--------|
+| ${date} | Initial creation |
+<!-- L3_END -->
+`;
+}
+
+function logContent(title) {
+  const date = today();
+  return `<!-- L1_START -->
+# L1 - Metadata
+date: ${date}
+type: Feature
+subject: ${title}
+short_story:
+status: In progress
+category:
+keywords: []
+<!-- L1_END -->
+
+---
+
+<!-- L2_START -->
+# L2 - Summary
+
+## Objective
+<!-- Why this work was undertaken -->
+
+## Problem
+<!-- What was observed -->
+
+## Solution
+<!-- How it was resolved -->
+<!-- L2_END -->
+
+---
+
+<!-- L3_START -->
+# L3 - Details
+
+<!-- Technical details, code changes, debugging steps... -->
+<!-- L3_END -->
+`;
+}
+
+module.exports = { permanentContent, logContent, slugify, slugifyLog, today };

package/package.json

@@ -1,10 +1,35 @@
 {
   "name": "openclew",
-  "version": "0.0.1",
-  "description": "Long Life Memory for LLMs",
+  "version": "0.1.0",
+  "description": "Long Life Memory for LLMs — structured project knowledge for AI agents and humans",
   "license": "MIT",
+  "bin": {
+    "openclew": "./bin/openclew.js"
+  },
+  "files": [
+    "bin/",
+    "lib/",
+    "templates/",
+    "hooks/",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "ai",
+    "llm",
+    "documentation",
+    "knowledge",
+    "memory",
+    "claude",
+    "cursor",
+    "copilot",
+    "agents"
+  ],
   "repository": {
     "type": "git",
     "url": "https://github.com/openclew/openclew"
+  },
+  "engines": {
+    "node": ">=16"
   }
 }

package/templates/log.md

@@ -0,0 +1,36 @@
+<!-- L1_START -->
+# L1 - Metadata
+date: YYYY-MM-DD
+type: Bug | Feature | Refactor | Doc | Deploy
+subject: Short title (< 60 chars)
+short_story: 1-2 sentences. What happened and what was the outcome. Include conclusions, not just process.
+status: Done | In progress | Abandoned
+category: Main domain (e.g. Auth, API, Database, UI...)
+keywords: [tag1, tag2, tag3]
+<!-- L1_END -->
+
+---
+
+<!-- L2_START -->
+# L2 - Summary
+
+## Objective
+<!-- Why this work was undertaken -->
+
+## Problem
+<!-- What was observed, context of discovery -->
+
+## Solution
+<!-- How it was resolved -->
+
+## Watch out
+<!-- Side effects, edge cases, things to know -->
+<!-- L2_END -->
+
+---
+
+<!-- L3_START -->
+# L3 - Details
+
+<!-- Technical details: code changes, debugging steps, commands, references... -->
+<!-- L3_END -->

package/templates/permanent.md

@@ -0,0 +1,45 @@
+<!-- L1_START -->
+# L1 - Metadata
+type: Reference | Architecture | Guide | Analysis
+subject: Short title (< 60 chars)
+created: YYYY-MM-DD
+updated: YYYY-MM-DD
+short_story: 1-2 sentences. What this doc covers and what it concludes. Must be enough to decide if you need to read further.
+status: Active | Stable | Archived
+category: Main domain (e.g. Auth, API, Database, UI...)
+keywords: [tag1, tag2, tag3]
+<!-- L1_END -->
+
+---
+
+<!-- L2_START -->
+# L2 - Summary
+
+## Objective
+<!-- Why this document exists, what need it covers -->
+
+## Key points
+<!-- 3-5 essential takeaways -->
+
+## Solution
+<!-- Recommended approach or pattern -->
+
+## Watch out
+<!-- Common pitfalls, edge cases, things to be aware of -->
+<!-- L2_END -->
+
+---
+
+<!-- L3_START -->
+# L3 - Details
+
+<!-- Full technical content: code examples, diagrams, references, deep dives... -->
+
+---
+
+## Changelog
+
+| Date | Change |
+|------|--------|
+| YYYY-MM-DD | Initial creation |
+<!-- L3_END -->