openclew 0.1.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 |
 |------|----------|------|------------|
-| **Permanent** | `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 |
 
-**Permanents** 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 permanent 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/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 -->
+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/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
@@ -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.
-- **Permanents are living** — 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,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 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
   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 refdocs
+  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,8 +2,8 @@
 """
 openclew index generator.
 
-Scans doc/_*.md (permanents) 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 permanents and logs with their L1 metadata."""
-    permanents = []
+    """Collect refdocs and logs with their metadata."""
+    refdocs = []
     logs = []
 
-    # Permanent 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:
-            permanents.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 permanents, logs
+    return refdocs, logs
 
 
-def generate_index(doc_dir, permanents, 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, permanents, logs):
         f"",
     ]
 
-    # Permanents section
-    lines.append("## Permanent docs")
+    # Refdocs section
+    lines.append("## Refdocs")
     lines.append("")
-    if permanents:
+    if refdocs:
         lines.append("| Document | Subject | Status | Category |")
         lines.append("|----------|---------|--------|----------|")
-        for f, meta in permanents:
+        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, 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 refdocs yet. Create one with `templates/refdoc.md`._")
     lines.append("")
 
     # Logs section (last 20)
@@ -137,7 +206,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(refdocs)}** refdocs, **{len(logs)}** logs.")
     lines.append("")
 
     return "\n".join(lines)
@@ -145,12 +214,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)
+    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(permanents)} permanents, {len(logs)} logs)")
+    print(f"Generated {index_path} ({len(refdocs)} refdocs, {len(logs)} logs)")
 
 
 if __name__ == "__main__":