openclew 0.2.0 → 0.2.1

package/README.md

@@ -70,152 +70,54 @@ L1 answers "should I read this?" L2 answers "what do I need to know?" L3 is ther
 
 | Type | Location | Role | Mutability |
 |------|----------|------|------------|
-| **Living** | `doc/_SUBJECT.md` | Living knowledge (architecture, conventions, decisions) | Updated over time |
+| **Refdoc** | `doc/_SUBJECT.md` | Reference knowledge (architecture, conventions, decisions) | Updated over time |
 | **Log** | `doc/log/YYYY-MM-DD_subject.md` | Frozen facts (what happened, what was decided) | Never modified |
 
-**Living docs** are your project's brain — they evolve as the project evolves.
+**Refdocs** 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 living docs tell you where you are. The logs tell you how you got here.
+Together, they form the thread. The refdocs tell you where you are. The logs tell you how you got here.
 
 ---
 
-## Quick start (5 minutes)
+## Quick start (2 minutes)
 
-### 1. Create the structure
+### 1. Install
 
 ```bash
-mkdir -p doc/log
+npx openclew init
 ```
 
-### 2. Copy the templates
+This:
+- Creates `doc/` with a guide, an example doc, and an example log
+- Detects your instruction file (CLAUDE.md, .cursorrules, AGENTS.md...)
+- Injects a block that teaches your agent about the doc structure
+- Installs a pre-commit hook that auto-generates `doc/_INDEX.md`
 
-Download from [`templates/`](templates/) or create manually:
+### 2. Start a session with your agent
 
-<details>
-<summary><b>templates/living.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 -->
+Ask it:
 
-## Key points
-<!-- 3-5 essential takeaways -->
+> Read doc/_USING_OPENCLEW.md and document our architecture.
 
-## Solution
-<!-- Recommended approach or pattern -->
-<!-- L2_END -->
+Your agent reads the guide, understands the L1/L2/L3 format, and creates `doc/_ARCHITECTURE.md` with your project's actual architecture.
 
----
-
-<!-- L3_START -->
-# L3 - Details
-
-<!-- Full technical content: examples, code, references... -->
+### 3. There is no step 3
 
-## Changelog
-
-| Date | Change |
-|------|--------|
-| YYYY-MM-DD | Initial creation |
-<!-- L3_END -->
-```
+Next session, your agent reads the index, finds the doc, has the context. No re-explanation needed. As your project evolves, your agent creates and updates docs during sessions — refdocs for ongoing knowledge, logs for frozen facts.
 
-</details>
+The index auto-regenerates on every commit. Never edit it manually.
 
 <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
+<summary><b>Manual setup</b> — if you prefer not to use the CLI</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 -->
-```
+1. Create `doc/` and `doc/log/`
+2. Copy templates from [`templates/`](templates/) (refdoc.md, log.md)
+3. Add the openclew block to your instruction file (see `doc/_USING_OPENCLEW.md` after init for the exact format)
+4. Copy [`hooks/generate-index.py`](hooks/generate-index.py) and wire it as a pre-commit hook
 
 </details>
 
-### 3. Write your first doc
-
-```bash
-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.
-
-### 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
-- 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)
-```
-
-### 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
@@ -263,7 +165,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.
-- **Living docs evolve** — They evolve as the project evolves.
+- **Refdocs evolve** — They evolve as the project evolves.
 - **Index is auto-generated** — Never edit `_INDEX.md` manually.
 
 ---

package/bin/openclew.js

@@ -10,7 +10,7 @@ openclew — Long Life Memory for LLMs
 
 Usage:
   openclew init                    Set up openclew in the current project
-  openclew new <title>             Create a living doc (evolves with the project)
+  openclew new <title>             Create a refdoc (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
@@ -23,7 +23,7 @@ Options:
 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
+  openclew new "API design"        3. Create your own refdocs
   git commit                       4. Index auto-regenerates on commit
 
 Docs have 3 levels: L1 (metadata) → L2 (summary) → L3 (details).

package/hooks/generate-index.py

@@ -2,8 +2,8 @@
 """
 openclew index generator.
 
-Scans doc/_*.md (living docs) and doc/log/*.md (logs),
-parses L1 metadata blocks, and generates doc/_INDEX.md.
+Scans doc/_*.md (refdocs) and doc/log/*.md (logs),
+parses metadata line + L1 blocks, and generates doc/_INDEX.md.
 
 Usage:
     python generate-index.py              # from project root
@@ -34,23 +34,67 @@ def find_doc_dir():
     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
+def parse_metadata_line(content):
+    """Extract metadata from the first line (before L1_START).
+
+    Format: openclew@VERSION · key: value · key: value · ...
+    """
+    meta = {}
+    first_line = content.split("\n", 1)[0].strip()
+    if not first_line.startswith("openclew@"):
+        return meta
+
+    parts = first_line.split(" · ")
+    for part in parts:
+        part = part.strip()
+        if part.startswith("openclew@"):
+            meta["version"] = part.split("@", 1)[1]
+            continue
+        if ":" in part:
+            key, _, value = part.partition(":")
+            meta[key.strip().lower()] = value.strip()
+
+    return meta
 
+
+def parse_l1(content):
+    """Extract L1 fields (subject, doc_brief) from L1_START/L1_END block."""
+    meta = {}
     match = re.search(
         r"<!--\s*L1_START\s*-->(.+?)<!--\s*L1_END\s*-->",
         content,
         re.DOTALL,
     )
     if not match:
-        return None
+        return meta
 
     block = match.group(1)
+
+    # Extract **subject:** value
+    subject_match = re.search(r"\*\*subject:\*\*\s*(.+)", block)
+    if subject_match:
+        meta["subject"] = subject_match.group(1).strip()
+
+    # Extract **doc_brief:** value
+    brief_match = re.search(r"\*\*doc_brief:\*\*\s*(.+)", block)
+    if brief_match:
+        meta["doc_brief"] = brief_match.group(1).strip()
+
+    return meta
+
+
+def parse_l1_legacy(content):
+    """Fallback parser for old format (key: value lines inside L1 block)."""
     meta = {}
+    match = re.search(
+        r"<!--\s*L1_START\s*-->(.+?)<!--\s*L1_END\s*-->",
+        content,
+        re.DOTALL,
+    )
+    if not match:
+        return meta
+
+    block = match.group(1)
     for line in block.splitlines():
         line = line.strip()
         if line.startswith("#") or not line:
@@ -62,31 +106,56 @@ def parse_l1(filepath):
     return meta
 
 
+def parse_file(filepath):
+    """Parse a file and return combined metadata + L1 fields."""
+    try:
+        content = filepath.read_text(encoding="utf-8")
+    except (OSError, UnicodeDecodeError):
+        return None
+
+    # Try new format first
+    meta_line = parse_metadata_line(content)
+    l1 = parse_l1(content)
+
+    if l1.get("subject"):
+        # New format
+        meta_line.update(l1)
+        return meta_line
+
+    # Fallback to legacy format
+    legacy = parse_l1_legacy(content)
+    if legacy:
+        meta_line.update(legacy)
+        return meta_line
+
+    return None
+
+
 def collect_docs(doc_dir):
-    """Collect living docs and logs with their L1 metadata."""
-    living_docs = []
+    """Collect refdocs and logs with their metadata."""
+    refdocs = []
     logs = []
 
-    # Living docs: doc/_*.md
+    # Refdocs: doc/_*.md
     for f in sorted(doc_dir.glob("_*.md")):
         if f.name == "_INDEX.md":
             continue
-        meta = parse_l1(f)
+        meta = parse_file(f)
         if meta:
-            living_docs.append((f, meta))
+            refdocs.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)
+            meta = parse_file(f)
             if meta:
                 logs.append((f, meta))
 
-    return living_docs, logs
+    return refdocs, logs
 
 
-def generate_index(doc_dir, living_docs, logs):
+def generate_index(doc_dir, refdocs, logs):
     """Generate _INDEX.md content."""
     now = datetime.now().strftime("%Y-%m-%d %H:%M")
     lines = [
@@ -97,13 +166,13 @@ def generate_index(doc_dir, living_docs, logs):
         f"",
     ]
 
-    # Living docs section
-    lines.append("## Living docs")
+    # Refdocs section
+    lines.append("## Refdocs")
     lines.append("")
-    if living_docs:
+    if refdocs:
         lines.append("| Document | Subject | Status | Category |")
         lines.append("|----------|---------|--------|----------|")
-        for f, meta in living_docs:
+        for f, meta in refdocs:
             name = f.name
             subject = meta.get("subject", "—")
             status = meta.get("status", "—")
@@ -111,7 +180,7 @@ def generate_index(doc_dir, living_docs, logs):
             rel_path = f.relative_to(doc_dir.parent)
             lines.append(f"| [{name}]({rel_path}) | {subject} | {status} | {category} |")
     else:
-        lines.append("_No living docs yet. Create one with `templates/living.md`._")
+        lines.append("_No refdocs yet. Create one with `templates/refdoc.md`._")
     lines.append("")
 
     # Logs section (last 20)
@@ -137,7 +206,7 @@ def generate_index(doc_dir, living_docs, logs):
 
     # Stats
     lines.append("---")
-    lines.append(f"**{len(living_docs)}** living docs, **{len(logs)}** logs.")
+    lines.append(f"**{len(refdocs)}** refdocs, **{len(logs)}** logs.")
     lines.append("")
 
     return "\n".join(lines)
@@ -145,12 +214,12 @@ def generate_index(doc_dir, living_docs, logs):
 
 def main():
     doc_dir = find_doc_dir()
-    living_docs, logs = collect_docs(doc_dir)
-    index_content = generate_index(doc_dir, living_docs, logs)
+    refdocs, logs = collect_docs(doc_dir)
+    index_content = generate_index(doc_dir, refdocs, logs)
 
     index_path = doc_dir / "_INDEX.md"
     index_path.write_text(index_content, encoding="utf-8")
-    print(f"Generated {index_path} ({len(living_docs)} living docs, {len(logs)} logs)")
+    print(f"Generated {index_path} ({len(refdocs)} refdocs, {len(logs)} logs)")
 
 
 if __name__ == "__main__":

package/lib/checkout.js

@@ -10,9 +10,18 @@
 const fs = require("fs");
 const path = require("path");
 const { execSync } = require("child_process");
-const { logContent, slugifyLog, today } = require("./templates");
+const { slugifyLog, today } = require("./templates");
 const { readConfig } = require("./config");
 
+function ocVersion() {
+  try {
+    const pkg = require(path.join(__dirname, "..", "package.json"));
+    return pkg.version;
+  } catch {
+    return "0.0.0";
+  }
+}
+
 const PROJECT_ROOT = process.cwd();
 const DOC_DIR = path.join(PROJECT_ROOT, "doc");
 const LOG_DIR = path.join(DOC_DIR, "log");
@@ -53,12 +62,12 @@ function collectGitActivity() {
     ? fs.readdirSync(LOG_DIR).filter((f) => f.startsWith(date))
     : [];
 
-  // Living docs
-  const livingDocs = fs.existsSync(DOC_DIR)
+  // Refdocs
+  const refdocs = 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 };
+  return { date, commits, uncommitted, files, existingLogs, refdocs };
 }
 
 function extractActions(commits) {
@@ -98,7 +107,7 @@ function typeLabel(type) {
 }
 
 function displaySummary(activity) {
-  const { date, commits, uncommitted, existingLogs, livingDocs } = activity;
+  const { date, commits, uncommitted, existingLogs, refdocs } = activity;
   const actions = extractActions(commits);
 
   console.log(`\nopenclew checkout — ${date}\n`);
@@ -152,10 +161,10 @@ function displaySummary(activity) {
   }
   console.log("");
 
-  // Living docs reminder
-  if (livingDocs.length > 0) {
-    console.log("  📚 Living docs — check if any need updating:");
-    for (const doc of livingDocs) {
+  // Refdocs reminder
+  if (refdocs.length > 0) {
+    console.log("  📚 Refdocs — check if any need updating:");
+    for (const doc of refdocs) {
       console.log(`     ${doc}`);
     }
     console.log("");
@@ -189,15 +198,14 @@ function generateSessionLog(activity, 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}
+  const ver = ocVersion();
+  const logType = actions.length === 1 ? actions[0].type === "fix" ? "Bug" : "Feature" : "Feature";
+  const content = `openclew@${ver} · date: ${date} · type: ${logType} · status: Done · category: · keywords: ${keywordsStr}
+
+<!-- L1_START -->
+**subject:** ${sessionTitle}
+
+**doc_brief:** ${actions.map((a) => a.desc).join(". ")}.
 <!-- L1_END -->
 
 ---

package/lib/init.js

@@ -15,7 +15,7 @@ const readline = require("readline");
 const { detectInstructionFiles, findAgentsMdCaseInsensitive } = require("./detect");
 const { inject, isAlreadyInjected } = require("./inject");
 const { writeConfig } = require("./config");
-const { guideContent, exampleLivingDocContent, exampleLogContent, today } = require("./templates");
+const { guideContent, exampleRefdocContent, exampleLogContent, today } = require("./templates");
 
 const PROJECT_ROOT = process.cwd();
 const DOC_DIR = path.join(PROJECT_ROOT, "doc");
@@ -150,6 +150,24 @@ fi`;
   return true;
 }
 
+function updateGitignore() {
+  const gitignorePath = path.join(PROJECT_ROOT, ".gitignore");
+  const entry = "doc/log/";
+
+  if (fs.existsSync(gitignorePath)) {
+    const content = fs.readFileSync(gitignorePath, "utf-8");
+    if (content.includes(entry)) {
+      console.log("  .gitignore already ignores doc/log/");
+      return;
+    }
+    fs.appendFileSync(gitignorePath, `\n${entry}\n`, "utf-8");
+    console.log("  Added doc/log/ to .gitignore");
+  } else {
+    fs.writeFileSync(gitignorePath, `${entry}\n`, "utf-8");
+    console.log("  Created .gitignore with doc/log/");
+  }
+}
+
 function copyGenerateIndex() {
   const src = path.join(__dirname, "..", "hooks", "generate-index.py");
   const dst = path.join(DOC_DIR, "generate-index.py");
@@ -179,11 +197,11 @@ function createDocs() {
     console.log("  doc/_USING_OPENCLEW.md already exists");
   }
 
-  // Example living doc
+  // Example refdoc
   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)");
+    fs.writeFileSync(examplePath, exampleRefdocContent(), "utf-8");
+    console.log("  Created doc/_ARCHITECTURE.md (example refdoc)");
   } else {
     console.log("  doc/_ARCHITECTURE.md already exists");
   }
@@ -218,12 +236,16 @@ async function main() {
   console.log("1. Project structure");
   createDirs();
 
-  // Step 2: Copy index generator
-  console.log("\n2. Index generator");
+  // Step 2: Gitignore
+  console.log("\n2. Gitignore");
+  updateGitignore();
+
+  // Step 3: Copy index generator
+  console.log("\n3. Index generator");
   copyGenerateIndex();
 
-  // Step 3: Entry point
-  console.log("\n3. Entry point");
+  // Step 4: Entry point
+  console.log("\n4. Entry point");
   const entryPoint = await resolveEntryPoint();
 
   if (entryPoint) {
@@ -241,20 +263,20 @@ async function main() {
     writeConfig({ entryPoint: null }, PROJECT_ROOT);
   }
 
-  // Step 4: Pre-commit hook
-  console.log("\n4. Pre-commit hook");
+  // Step 5: Pre-commit hook
+  console.log("\n5. Pre-commit hook");
   if (noHook) {
     console.log("  Skipping (--no-hook)");
   } else {
     installPreCommitHook();
   }
 
-  // Step 5: Docs
-  console.log("\n5. Docs");
+  // Step 6: Docs
+  console.log("\n6. Docs");
   createDocs();
 
-  // Step 6: Generate index
-  console.log("\n6. Index");
+  // Step 7: Generate index
+  console.log("\n7. Index");
   runIndexGenerator();
 
   // Done

package/lib/inject.js

@@ -12,7 +12,7 @@ This file is the **entry point** for project documentation.
 **Doc-first rule:** before any task, read \`doc/_INDEX.md\` to find docs related to the task. Read them before exploring code.
 
 Two types of docs in \`doc/\`:
-- **Living docs** (\`doc/_*.md\`) — evolve with the project (architecture, conventions, decisions)
+- **Refdocs** (\`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).

package/lib/new-doc.js

@@ -1,10 +1,10 @@
 /**
- * openclew new <title> — create a new living doc.
+ * openclew new <title> — create a new refdoc.
  */
 
 const fs = require("fs");
 const path = require("path");
-const { livingContent, slugify } = require("./templates");
+const { refdocContent, slugify } = require("./templates");
 const { readConfig } = require("./config");
 
 const args = process.argv.slice(2);
@@ -37,7 +37,7 @@ if (fs.existsSync(filepath)) {
   process.exit(1);
 }
 
-fs.writeFileSync(filepath, livingContent(title), "utf-8");
+fs.writeFileSync(filepath, refdocContent(title), "utf-8");
 console.log(`Created doc/${filename}`);
 console.log("");
 console.log("Next: open the file and fill in:");

package/lib/new-log.js

@@ -42,7 +42,7 @@ 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("  L1 — subject + doc_brief (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,8 +1,10 @@
 /**
- * Template content for living docs and logs.
+ * Template content for refdocs and logs.
  * Embedded here so the CLI works standalone without needing to locate template files.
  */
 
+const path = require("path");
+
 function today() {
   return new Date().toISOString().slice(0, 10);
 }
@@ -21,18 +23,24 @@ function slugifyLog(title) {
     .replace(/^-|-$/g, "");
 }
 
-function livingContent(title) {
+function ocVersion() {
+  try {
+    const pkg = require(path.join(__dirname, "..", "package.json"));
+    return pkg.version;
+  } catch {
+    return "0.0.0";
+  }
+}
+
+function refdocContent(title) {
   const date = today();
-  return `<!-- L1_START -->
-# L1 - Metadata
-type: Reference
-subject: ${title}
-created: ${date}
-updated: ${date}
-short_story:
-status: Active
-category:
-keywords: []
+  const ver = ocVersion();
+  return `openclew@${ver} · created: ${date} · updated: ${date} · type: Reference · status: Active · category: · keywords: []
+
+<!-- L1_START -->
+**subject:** ${title}
+
+**doc_brief:**
 <!-- L1_END -->
 
 ---
@@ -67,15 +75,13 @@ keywords: []
 
 function logContent(title) {
   const date = today();
-  return `<!-- L1_START -->
-# L1 - Metadata
-date: ${date}
-type: Feature
-subject: ${title}
-short_story:
-status: In progress
-category:
-keywords: []
+  const ver = ocVersion();
+  return `openclew@${ver} · date: ${date} · type: Feature · status: In progress · category: · keywords: []
+
+<!-- L1_START -->
+**subject:** ${title}
+
+**doc_brief:**
 <!-- L1_END -->
 
 ---
@@ -109,16 +115,13 @@ keywords: []
  */
 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]
+  const ver = ocVersion();
+  return `openclew@${ver} · created: ${date} · updated: ${date} · type: Guide · status: Active · category: Documentation · keywords: [openclew, L1, L2, L3, index, refdoc, log]
+
+<!-- L1_START -->
+**subject:** How openclew works
+
+**doc_brief:** How openclew structures project knowledge in 3 levels (L1/L2/L3) so AI agents and humans navigate efficiently.
 <!-- L1_END -->
 
 ---
@@ -136,7 +139,7 @@ Before starting any task, read \`doc/_INDEX.md\` to find docs related to the tas
 
 ## Two types of docs
 
-**Living docs** (\`doc/_*.md\`): knowledge that evolves with the project.
+**Refdocs** (\`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\`)
 
@@ -144,13 +147,17 @@ Naming: \`doc/_UPPER_SNAKE_CASE.md\` (e.g. \`doc/_AUTH_DESIGN.md\`)
 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
+## Document structure
+
+Every doc has a metadata line + 3 levels. Read only what you need:
 
-Every doc has 3 levels. Read only what you need:
+**Line 1 — Metadata**: version, date, type, status, category, keywords. For indexing and triage.
 
-- **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.
+**L1 — Subject + Brief** (~40 tokens): what the doc is about and what it concludes. 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
 
@@ -163,21 +170,17 @@ Never edit it manually. To force a rebuild: \`openclew index\`
 <!-- L3_START -->
 # L3 - Details
 
-## Creating a living doc
+## Creating a refdoc
 
 Create \`doc/_TITLE.md\` (uppercase snake_case) with this structure:
 
 \`\`\`
+openclew@${ver} · created: YYYY-MM-DD · updated: YYYY-MM-DD · type: Reference · status: Active · category: · keywords: []
+
 <!-- L1_START -->
-# L1 - Metadata
-type: Reference
-subject: Title
-created: YYYY-MM-DD
-updated: YYYY-MM-DD
-short_story:
-status: Active
-category:
-keywords: []
+**subject:** Title
+
+**doc_brief:**
 <!-- L1_END -->
 
 ---
@@ -205,15 +208,12 @@ keywords: []
 Create \`doc/log/YYYY-MM-DD_slug.md\` (lowercase, hyphens) with this structure:
 
 \`\`\`
+openclew@${ver} · date: YYYY-MM-DD · type: Feature · status: In progress · category: · keywords: []
+
 <!-- L1_START -->
-# L1 - Metadata
-date: YYYY-MM-DD
-type: Feature
-subject: Title
-short_story:
-status: In progress
-category:
-keywords: []
+**subject:** Title
+
+**doc_brief:**
 <!-- L1_END -->
 
 ---
@@ -243,9 +243,10 @@ Logs are immutable — once the session ends, the log is never modified.
 
 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
+3. Read L1 (subject + brief) of relevant docs to confirm relevance
+4. Read L2 for context
+5. Only read L3 when you need implementation details
+6. After significant work: create or update refdocs and logs directly
 
 The index (\`doc/_INDEX.md\`) auto-regenerates on every git commit. To force a rebuild: \`openclew index\`
 
@@ -261,20 +262,17 @@ The index (\`doc/_INDEX.md\`) auto-regenerates on every git commit. To force a r
 }
 
 /**
- * Example living doc — shows what a filled-in doc looks like.
+ * Example refdoc — shows what a filled-in doc looks like.
  */
-function exampleLivingDocContent() {
+function exampleRefdocContent() {
   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]
+  const ver = ocVersion();
+  return `openclew@${ver} · created: ${date} · updated: ${date} · type: Reference · status: Active · category: Architecture · keywords: [architecture, overview, components]
+
+<!-- L1_START -->
+**subject:** Architecture overview
+
+**doc_brief:** High-level architecture of the project — components, data flow, key decisions.
 <!-- L1_END -->
 
 ---
@@ -298,7 +296,7 @@ Document the high-level architecture so new contributors and AI agents understan
 
 <!-- Replace this with your actual architecture details -->
 
-This is an example living doc created by \`openclew init\`.
+This is an example refdoc created by \`openclew init\`.
 Edit it to document your project's architecture, or delete it and create your own.
 
 ---
@@ -317,15 +315,13 @@ Edit it to document your project's architecture, or delete it and create your ow
  */
 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]
+  const ver = ocVersion();
+  return `openclew@${ver} · date: ${date} · type: Feature · status: Done · category: Tooling · keywords: [openclew, setup, documentation]
+
+<!-- L1_START -->
+**subject:** Set up openclew
+
+**doc_brief:** Initialized openclew for structured project knowledge. Created doc/ structure, git hook, guide, and example docs.
 <!-- L1_END -->
 
 ---
@@ -340,7 +336,7 @@ Set up structured documentation so AI agents and new contributors can navigate p
 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).
+Installed openclew. Every doc now has a metadata line (for triage) + L1 (subject and brief), L2 (summary for context), L3 (details when needed).
 The index auto-regenerates on each commit via a git hook.
 <!-- L2_END -->
 
@@ -351,16 +347,16 @@ The index auto-regenerates on each commit via a git hook.
 
 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\`).
+For evolving knowledge, use refdocs (\`doc/_*.md\`).
 <!-- L3_END -->
 `;
 }
 
 module.exports = {
-  livingContent,
+  refdocContent,
   logContent,
   guideContent,
-  exampleLivingDocContent,
+  exampleRefdocContent,
   exampleLogContent,
   slugify,
   slugifyLog,

package/package.json

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

package/templates/log.md

@@ -1,12 +1,9 @@
+openclew@VERSION · date: YYYY-MM-DD · type: Bug | Feature | Refactor | Doc | Deploy · status: Done | In progress | Abandoned · category: Main domain · keywords: [tag1, tag2, tag3]
+
 <!-- 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]
+**subject:** Short title (< 60 chars)
+
+**doc_brief:** 1-2 sentences. What happened and what was the outcome. Include conclusions, not just process.
 <!-- L1_END -->
 
 ---

package/templates/{living.md → refdoc.md}

@@ -1,13 +1,9 @@
+openclew@VERSION · created: YYYY-MM-DD · updated: YYYY-MM-DD · type: Reference | Architecture | Guide | Analysis · status: Active | Stable | Archived · category: Main domain · keywords: [tag1, tag2, tag3]
+
 <!-- 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]
+**subject:** Short title (< 60 chars)
+
+**doc_brief:** 1-2 sentences. What this doc covers and what it concludes. Must be enough to decide if you need to read further.
 <!-- L1_END -->
 
 ---