openclew 0.2.0 → 0.3.0

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,18 +147,33 @@ 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
 
 \`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\`
+
+## Using with OpenClaw (or any agent framework)
+
+openclew handles **project knowledge** — what your project knows, what was decided, what happened.
+Agent frameworks (OpenClaw, Claude Code, Cursor, etc.) handle **agent behavior** — identity, tools, memory.
+
+They work together:
+- Your framework's workspace memory (\`MEMORY.md\`, \`SOUL.md\`, etc.) = agent-level, cross-project
+- openclew's \`doc/\` = project-level, shared across all agents and sessions
+
+openclew injects into your project's instruction file (AGENTS.md, CLAUDE.md, .cursorrules, etc.) — it doesn't replace or conflict with your framework's configuration.
 <!-- L2_END -->
 
 ---
@@ -163,21 +181,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 +219,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 +254,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 +273,37 @@ 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(existingInstructions) {
   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();
+
+  // Strip openclew block from existing instructions to avoid duplication
+  let seedContent = "";
+  if (existingInstructions) {
+    seedContent = existingInstructions
+      .replace(/<!--\s*openclew_START\s*-->[\s\S]*?<!--\s*openclew_END\s*-->/g, "")
+      .trim();
+  }
+
+  const seedSection = seedContent
+    ? `## From existing project instructions
+
+${seedContent}
+
+## What to do next
+<!-- Review the above (imported from your instruction file) and reorganize into the sections below. Then delete this section. -->
+
+`
+    : "";
+
+  return `openclew@${ver} · created: ${date} · updated: ${date} · type: Reference · status: Active · category: Architecture · keywords: [architecture, overview, components]
+
+<!-- L1_START -->
+**subject:** Architecture overview
+
+**doc_brief:** <!-- ONE LINE: What does this project do, what's the main stack, how is it deployed? -->
 <!-- L1_END -->
 
 ---
@@ -282,13 +311,25 @@ keywords: [architecture, overview, components]
 <!-- 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
+${seedSection}## What this project does
+<!-- 1-2 sentences. What problem does it solve? Who uses it? -->
+
+## Stack
+<!-- List the main technologies: language, framework, database, key libraries. -->
+
+## How it's organized
+<!-- Describe the main directories and what lives where. e.g.:
+- src/routes/ — API endpoints
+- src/services/ — business logic
+- src/models/ — database models
+-->
+
+## Key decisions
+<!-- List 2-5 architectural choices that someone new needs to know. e.g.:
+- Auth via JWT (not sessions) because the API is stateless
+- PostgreSQL over MongoDB because we need relational queries
+- All validation happens in middleware, not in route handlers
+-->
 <!-- L2_END -->
 
 ---
@@ -296,10 +337,21 @@ Document the high-level architecture so new contributors and AI agents understan
 <!-- L3_START -->
 # L3 - Details
 
-<!-- Replace this with your actual architecture details -->
+## Data flow
+<!-- How does a request travel through the system? e.g.:
+Client → route → middleware (auth, validation) → service → repository → DB
+-->
+
+## External dependencies
+<!-- APIs, services, or systems this project talks to. -->
 
-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.
+## How to run
+<!-- Commands to start the project locally. e.g.:
+npm install && npm run dev
+-->
+
+## Known constraints
+<!-- Limits, technical debt, or things that don't scale. -->
 
 ---
 
@@ -307,7 +359,7 @@ Edit it to document your project's architecture, or delete it and create your ow
 
 | Date | Change |
 |------|--------|
-| ${date} | Created by openclew init (example) |
+| ${date} | Created by openclew init — fill this in! |
 <!-- L3_END -->
 `;
 }
@@ -317,15 +369,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 +390,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 +401,142 @@ 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 -->
+`;
+}
+
+/**
+ * Framework integration guide — created by init alongside the main guide.
+ * Explains how openclew works with workflow frameworks (BMAD, Spec Kit, Kiro...).
+ */
+function frameworkIntegrationContent() {
+  const date = today();
+  const ver = ocVersion();
+  return `openclew@${ver} · created: ${date} · updated: ${date} · type: Guide · status: Active · category: Integration · keywords: [BMAD, Spec Kit, Kiro, workflow, framework, integration]
+
+<!-- L1_START -->
+**subject:** How to use openclew with workflow frameworks (BMAD, Spec Kit, Kiro...)
+
+**doc_brief:** openclew handles knowledge, your framework handles process. Covers concrete use cases, integration patterns, and what goes where. Works with any spec-driven methodology.
+<!-- L1_END -->
+
+---
+
+<!-- L2_START -->
+# L2 - Summary
+
+## The split
+
+Workflow frameworks (BMAD, Spec Kit, Kiro...) solve: *"my agent doesn't follow a process."*
+openclew solves: *"my agent forgets everything between sessions."*
+
+They're complementary. Use both.
+
+| Your framework does | openclew does |
+|---------------------|---------------|
+| Structures the workflow (who does what, in what order) | Structures the knowledge (what to remember, where to find it) |
+| Produces artifacts (PRD, architecture, stories, retro) | Persists them so they're found automatically next session |
+| Scoped to one sprint/feature | Scoped to the lifetime of the codebase |
+
+## Use cases
+
+### UC1 — PRD forgotten after creation
+
+You create a PRD with your framework. Two weeks later, a new session starts. The agent doesn't know the PRD exists.
+
+**With openclew:** The PRD is persisted as \`doc/_PRD_AUTH.md\` (L1 scannable). The agent scans the index at session start and finds it automatically.
+
+### UC2 — Sprint decisions lost
+
+Three stories completed in a sprint. Decisions were made (API design, tradeoffs, rejected approaches). They live in chat history — gone.
+
+**With openclew:** Each completed story produces a log (\`doc/log/YYYY-MM-DD_story-auth-flow.md\`). Immutable. When the project resumes, the agent sees what was decided and why.
+
+### UC3 — Retrospective lessons not reused
+
+Your framework runs a retro. Lessons are identified. They go into an output file that nobody reads again.
+
+**With openclew:** Lessons go into \`doc/_LESSONS_LEARNED.md\` — a living refdoc, updated after each retro. Future sprints consult it automatically via the index.
+
+### UC4 — New teammate onboarding
+
+A new developer (or a new agent session) joins mid-project. No context.
+
+**With openclew:** Read \`doc/_INDEX.md\` → scan L1s → read L2s of relevant docs → full context in minutes. Same docs for humans and agents.
+
+### UC5 — Framework needs project context
+
+Your framework's agents (PM, Architect, Dev) start from generic prompts. They don't know your project's conventions, architecture, or past decisions.
+
+**With openclew:** Point your framework's knowledge config at \`doc/\`. Agents read refdocs as context before producing artifacts.
+
+<!-- L2_END -->
+
+---
+
+<!-- L3_START -->
+# L3 - Details
+
+## Integration pattern
+
+\`\`\`
+Framework (process)              openclew (knowledge)
+───────────────────              ────────────────────
+Create PRD            →          Save as doc/_PRD_FEATURE.md
+Architecture design   →          Save as doc/_ARCHITECTURE.md
+Sprint planning       →          Log as doc/log/YYYY-MM-DD_sprint-N.md
+Story completed       →          Log as doc/log/YYYY-MM-DD_story-ID.md
+Retrospective         →          Update doc/_LESSONS_LEARNED.md
+───────────────────              ────────────────────
+Next sprint starts    ←          Agent reads index, finds all of the above
+\`\`\`
+
+## Mapping: framework artifacts → openclew docs
+
+| Framework artifact | openclew type | Naming | Mutability |
+|--------------------|---------------|--------|------------|
+| PRD | Refdoc | \`doc/_PRD_FEATURE.md\` | Updated as requirements evolve |
+| Architecture decision | Refdoc | \`doc/_ARCHITECTURE.md\` | Updated as design evolves |
+| Sprint plan | Log | \`doc/log/YYYY-MM-DD_sprint-N.md\` | Frozen (snapshot of the plan) |
+| Completed story | Log | \`doc/log/YYYY-MM-DD_story-ID.md\` | Frozen (what was done) |
+| Retrospective | Log + Refdoc | Log for the session, refdoc for accumulated lessons | Log frozen, refdoc updated |
+| Tech spec | Refdoc | \`doc/_SPEC_FEATURE.md\` | Updated until implemented |
+
+## BMAD-specific integration
+
+BMAD uses a \`project_knowledge\` config that points agents to project context. Point it at \`doc/\`:
+
+\`\`\`yaml
+# _bmad/bmm/config.yaml
+project_knowledge: doc/
+\`\`\`
+
+BMAD agents (PM, Architect, Dev, QA) will read openclew docs as context before producing artifacts.
+
+## What openclew does NOT do
+
+- Does not replace your framework's workflow or personas
+- Does not impose a development process
+- Does not require any specific framework — works standalone
+
+---
+
+## Changelog
+
+| Date | Change |
+|------|--------|
+| ${date} | Created by openclew init |
 <!-- L3_END -->
 `;
 }
 
 module.exports = {
-  livingContent,
+  refdocContent,
   logContent,
   guideContent,
-  exampleLivingDocContent,
+  frameworkIntegrationContent,
+  exampleRefdocContent,
   exampleLogContent,
   slugify,
   slugifyLog,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openclew",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Long Life Memory for LLMs — structured project knowledge for AI agents and humans",
   "license": "MIT",
   "bin": {
@@ -8,10 +8,22 @@
   },
   "files": [
     "bin/",
-    "lib/",
+    "lib/checkout.js",
+    "lib/config.js",
+    "lib/detect.js",
+    "lib/index-gen.js",
+    "lib/init.js",
+    "lib/inject.js",
+    "lib/mcp-server.js",
+    "lib/new-doc.js",
+    "lib/new-log.js",
+    "lib/search.js",
+    "lib/status.js",
+    "lib/templates.js",
     "templates/",
-    "hooks/",
+    "skills/",
     "README.md",
+    "UPGRADING.md",
     "LICENSE"
   ],
   "keywords": [
@@ -29,6 +41,15 @@
     "type": "git",
     "url": "https://github.com/openclew/openclew"
   },
+  "author": "Raphaël Flambard <raphael@ralpha.fr>",
+  "contributors": [
+    "Adrien Cocuaud <adrien@ralpha.fr>",
+    "Victor Ripplinger"
+  ],
+  "homepage": "https://github.com/openclew/openclew#readme",
+  "bugs": {
+    "url": "https://github.com/openclew/openclew/issues"
+  },
   "engines": {
     "node": ">=16"
   }

package/skills/openclew-checkpoint/SKILL.md

@@ -0,0 +1,36 @@
+---
+name: openclew-checkpoint
+description: End-of-session checkpoint. Summarizes git activity, creates a session log, and regenerates the doc index. Use at the end of a work session to persist what was done.
+user-invocable: true
+---
+
+# openclew checkpoint — End-of-session summary
+
+Run this at the end of a work session to capture what happened.
+
+## Command
+
+```bash
+npx openclew checkout
+```
+
+## What it does
+
+1. Collects today's git activity (commits, changed files, uncommitted changes)
+2. Displays a summary table
+3. Creates a session log in `doc/log/YYYY-MM-DD_<topic>.md`
+4. Regenerates `doc/_INDEX.md`
+
+## When to use
+
+- End of a coding session
+- After completing a feature or bug fix
+- Before switching to a different project
+- When you want to leave a trace for the next session (yours or someone else's)
+
+## Other useful commands
+
+- `npx openclew add ref "Title"` — Create a reference doc for lasting knowledge
+- `npx openclew add log "Title"` — Create a log manually (for mid-session notes)
+- `npx openclew status` — Health dashboard (missing briefs, stale docs)
+- `npx openclew search "query"` — Find docs by keyword

package/skills/openclew-init/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: openclew-init
+description: Set up openclew structured documentation in the current project. Creates doc/ with L1/L2/L3 knowledge base, auto-generated index, and injects context into your instruction file.
+user-invocable: true
+---
+
+# openclew init — Set up project knowledge
+
+Run this to add structured documentation to your project.
+
+## What it does
+
+1. Creates `doc/` and `doc/log/` directories
+2. Detects your existing instruction file (AGENTS.md, CLAUDE.md, .cursorrules, etc.)
+3. Injects a knowledge block so agents automatically consult project docs
+4. Creates starter docs: guide, architecture template, example log
+5. Generates `doc/_INDEX.md` (auto-rebuilt on every commit)
+6. Installs a git pre-commit hook for index regeneration
+
+## Command
+
+```bash
+npx openclew init
+```
+
+## Options
+
+- `--no-inject` — Skip injection into instruction file
+- `--no-hook` — Skip git hook installation
+
+## After setup
+
+Your agent will now read `doc/_INDEX.md` before starting tasks. To add knowledge:
+
+- `npx openclew add ref "Title"` — Create a reference doc (architecture, conventions, decisions)
+- `npx openclew add log "Title"` — Create a session log (frozen facts)
+- `npx openclew search "query"` — Search existing docs
+- `npx openclew checkout` — End-of-session summary
+
+## How it works with OpenClaw
+
+openclew handles **project knowledge** (what your project knows, what was decided, what happened).
+OpenClaw handles **agent identity** (personality, memory, tools, messaging).
+
+They're complementary:
+- OpenClaw's `MEMORY.md` = your agent's personal memory across all projects
+- openclew's `doc/` = this project's shared knowledge across all agents and sessions
+
+openclew injects into your project's `AGENTS.md` (or any instruction file). This doesn't conflict with OpenClaw's workspace `AGENTS.md` — they live in different locations.

package/skills/openclew-search/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: openclew-search
+description: Search project documentation by keyword. Searches L1 metadata (subject, doc_brief, category, keywords) across all refdocs and logs. Returns results sorted by relevance.
+user-invocable: true
+---
+
+# openclew search — Find relevant docs
+
+Search your project's knowledge base by keyword.
+
+## Command
+
+```bash
+npx openclew search "<query>"
+```
+
+## Examples
+
+```bash
+npx openclew search "auth"           # Find docs about authentication
+npx openclew search "API design"     # Multi-word search
+npx openclew search "bug"            # Find bug-related logs
+```
+
+## What it searches
+
+- **subject** (weight: 3×) — document title
+- **doc_brief** (weight: 2×) — one-line summary
+- **keywords** (weight: 2×) — tags
+- **category** (weight: 1.5×) — domain
+- **type** (weight: 1×) — Reference, Guide, Bug, Feature...
+- **status** (weight: 0.5×) — Active, Done, Archived...
+
+## Reading results
+
+Each result shows:
+- Icon: 📘 refdoc or 📝 log
+- Subject and status
+- File path (relative)
+- Brief description
+
+After finding a doc, read it at the level you need:
+- **L1** (between `L1_START`/`L1_END`) — subject + brief, ~40 tokens
+- **L2** (between `L2_START`/`L2_END`) — summary, essential context
+- **L3** (between `L3_START`/`L3_END`) — full details, only when deep-diving