openclew 0.2.1 → 0.4.0

package/commands/oc-init.md

@@ -0,0 +1,27 @@
+<!-- openclew-managed -->
+# oc-init — Set up openclew in the current project
+
+Initialize structured documentation so AI agents and humans navigate project knowledge efficiently.
+
+**Usage:** `/oc-init`
+
+## Sequence
+
+1. Run `npx openclew init`
+2. Display what was created
+3. Read the generated guide (`doc/_USING_OPENCLEW.md`) to understand the setup
+4. Propose creating a first architecture doc:
+   - "Want me to create `doc/_ARCHITECTURE.md` based on the current project structure?"
+   - If yes: analyze the project (main dirs, stack, key files) and fill in the template
+
+## After setup
+
+The agent will now consult `doc/_INDEX.md` before starting tasks. Available commands:
+
+- `/oc-search <query>` — Search existing docs
+- `/oc-status` — Health dashboard
+- `/oc-checkout` — End-of-session summary
+
+To add knowledge manually:
+- `npx openclew add ref "Title"` — Create a reference doc
+- `npx openclew add log "Title"` — Create a session log

package/commands/oc-peek.md

@@ -0,0 +1,41 @@
+<!-- openclew-managed -->
+# oc-peek — Discover project knowledge before working
+
+First reflex before exploring a project: shows the instruction file and lists all available docs.
+
+**Usage:** `/oc-peek` (no arguments, uses the current project)
+
+## Sequence
+
+### Step 1: Run the CLI
+
+```bash
+npx openclew peek
+```
+
+This lists:
+- The instruction file (CLAUDE.md / AGENTS.md) path
+- All refdocs in `doc/` with their subjects
+- All `_*.md` files outside `doc/` (prompts, scripts, etc.)
+- Subdirectories of `doc/`
+
+### Step 2: Display the instruction file
+
+Read the instruction file (CLAUDE.md or AGENTS.md) and display it **in full** — do not summarize.
+
+### Step 3: Display the refdoc list
+
+Display the CLI output as-is. This is a **listing only** — do not read the refdocs at this stage.
+
+## Rules
+
+- **Do not summarize** the instruction file — display it integrally
+- **Do not read** the refdocs — list file names only
+- If no instruction file exists: indicate `(no instruction file found)`
+- If no `doc/` directory exists: indicate `(no doc/ directory)`
+
+## Related commands
+
+- `/oc-search <query>` — Search docs by keyword
+- `/oc-status` — Documentation health dashboard
+- `/oc-checkout` — End-of-session summary

package/commands/oc-search.md

@@ -0,0 +1,25 @@
+<!-- openclew-managed -->
+# oc-search — Search project documentation
+
+Search your project's knowledge base by keyword.
+
+**Usage:** `/oc-search <query>`
+
+## Sequence
+
+1. Run `npx openclew search "$ARGUMENTS"` to get results
+2. Display results to the user
+3. If results found: propose to read the most relevant doc(s) at L2 level
+4. If no results: suggest alternative keywords or propose creating a new doc
+
+## Reading results
+
+After finding a doc, read it progressively:
+- **L1** (between `L1_START`/`L1_END`) — subject + brief, ~40 tokens. "Should I read this?"
+- **L2** (between `L2_START`/`L2_END`) — summary, essential context
+- **L3** (between `L3_START`/`L3_END`) — full details, only when deep-diving
+
+## Related commands
+
+- `/oc-status` — Health dashboard (missing briefs, stale docs)
+- `/oc-checkout` — End-of-session summary

package/commands/oc-status.md

@@ -0,0 +1,20 @@
+<!-- openclew-managed -->
+# oc-status — Documentation health dashboard
+
+Display the health status of project documentation.
+
+**Usage:** `/oc-status`
+
+## Sequence
+
+1. Run `npx openclew status` to get the dashboard
+2. Display results to the user
+3. If issues found, propose actions:
+   - **Missing doc_brief**: "These docs have empty briefs — want me to fill them in?"
+   - **Stale docs**: "These docs haven't been updated in a while — want me to review them?"
+   - **No recent logs**: "No log created recently — want me to create one for this session?"
+
+## Related commands
+
+- `/oc-search <query>` — Search docs by keyword
+- `/oc-checkout` — End-of-session summary (also creates logs)

package/lib/checkout.js

@@ -253,11 +253,9 @@ ${commitList}
 }
 
 function regenerateIndex() {
-  const indexScript = path.join(DOC_DIR, "generate-index.py");
-  if (!fs.existsSync(indexScript)) return;
-
   try {
-    execSync(`python3 "${indexScript}" "${DOC_DIR}"`, { stdio: "pipe" });
+    const { writeIndex } = require("./index-gen");
+    writeIndex(DOC_DIR);
     console.log("  📋 Regenerated doc/_INDEX.md");
   } catch {
     // Silent — index will be regenerated on next commit anyway

package/lib/index-gen.js

@@ -1,40 +1,115 @@
 /**
  * openclew index — regenerate doc/_INDEX.md
  *
- * Wraps hooks/generate-index.py. Falls back to a JS implementation
- * if Python is not available.
+ * Pure JS implementation. Reuses parsers from search.js (SSOT).
+ * Zero dependencies — Node 16+ standard library only.
  */
 
-const { execSync } = require("child_process");
 const fs = require("fs");
 const path = require("path");
+const { collectDocs } = require("./search");
 
-const docDir = path.join(process.cwd(), "doc");
+/**
+ * Generate _INDEX.md content from parsed docs.
+ *
+ * @param {string} docDir - Absolute path to doc/ directory
+ * @returns {string} Generated index content
+ */
+function generateIndex(docDir) {
+  const docs = collectDocs(docDir);
+  const refdocs = docs.filter((d) => d.kind === "refdoc");
+  const logs = docs.filter((d) => d.kind === "log");
+
+  const now = new Date();
+  const timestamp = `${now.getFullYear()}-${String(now.getMonth() + 1).padStart(2, "0")}-${String(now.getDate()).padStart(2, "0")} ${String(now.getHours()).padStart(2, "0")}:${String(now.getMinutes()).padStart(2, "0")}`;
+
+  const lines = [
+    "# Project Knowledge Index",
+    "",
+    `> Auto-generated by [openclew](https://github.com/openclew/openclew) on ${timestamp}.`,
+    "> Do not edit manually — rebuilt from L1 metadata on every commit.",
+    "",
+  ];
+
+  // Refdocs section
+  lines.push("## Refdocs");
+  lines.push("");
+  if (refdocs.length) {
+    lines.push("| Document | Subject | Status | Category |");
+    lines.push("|----------|---------|--------|----------|");
+    for (const doc of refdocs) {
+      const name = path.basename(doc.filepath);
+      const subject = doc.meta.subject || "—";
+      const status = doc.meta.status || "—";
+      const category = doc.meta.category || "—";
+      const relPath = path.relative(path.dirname(docDir), doc.filepath);
+      lines.push(`| [${name}](${relPath}) | ${subject} | ${status} | ${category} |`);
+    }
+  } else {
+    lines.push("_No refdocs yet. Create one with `npx openclew add ref \"Title\"`._");
+  }
+  lines.push("");
+
+  // Logs section (last 20)
+  const displayLogs = logs.slice(0, 20);
+  lines.push("## Recent logs");
+  lines.push("");
+  if (displayLogs.length) {
+    lines.push("| Date | Subject | Status | Category |");
+    lines.push("|------|---------|--------|----------|");
+    for (const doc of displayLogs) {
+      const date = doc.meta.date || path.basename(doc.filepath).slice(0, 10);
+      const subject = doc.meta.subject || "—";
+      const status = doc.meta.status || "—";
+      const category = doc.meta.category || "—";
+      const relPath = path.relative(path.dirname(docDir), doc.filepath);
+      lines.push(`| ${date} | [${subject}](${relPath}) | ${status} | ${category} |`);
+    }
+    if (logs.length > 20) {
+      lines.push("");
+      lines.push(`_${logs.length - 20} older logs not shown._`);
+    }
+  } else {
+    lines.push("_No logs yet. Create one with `npx openclew add log \"Title\"`._");
+  }
+  lines.push("");
 
-if (!fs.existsSync(docDir)) {
-  console.error("No doc/ directory found. Run 'openclew init' first.");
-  process.exit(1);
+  // Stats
+  lines.push("---");
+  lines.push(`**${refdocs.length}** refdocs, **${logs.length}** logs.`);
+  lines.push("");
+
+  return lines.join("\n");
 }
 
-// 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."
-    );
+/**
+ * Write _INDEX.md to disk.
+ *
+ * @param {string} docDir - Absolute path to doc/ directory
+ * @returns {{ refdocs: number, logs: number }} Counts
+ */
+function writeIndex(docDir) {
+  const content = generateIndex(docDir);
+  const indexPath = path.join(docDir, "_INDEX.md");
+  fs.writeFileSync(indexPath, content, "utf-8");
+
+  const docs = collectDocs(docDir);
+  const refdocs = docs.filter((d) => d.kind === "refdoc").length;
+  const logs = docs.filter((d) => d.kind === "log").length;
+  return { refdocs, logs };
+}
+
+// CLI runner
+if (require.main === module || process.argv.includes("index")) {
+  const docDir = process.argv[2] || path.join(process.cwd(), "doc");
+
+  if (!fs.existsSync(docDir)) {
+    console.error("No doc/ directory found. Run 'openclew init' first.");
     process.exit(1);
   }
+
+  const { refdocs, logs } = writeIndex(docDir);
+  console.log(`Generated doc/_INDEX.md (${refdocs} refdocs, ${logs} logs)`);
 }
 
-console.error("generate-index.py not found. Run 'openclew init' first.");
-process.exit(1);
+module.exports = { generateIndex, writeIndex };

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, exampleRefdocContent, exampleLogContent, today } = require("./templates");
+const { guideContent, frameworkIntegrationContent, exampleRefdocContent, exampleLogContent, today } = require("./templates");
 
 const PROJECT_ROOT = process.cwd();
 const DOC_DIR = path.join(PROJECT_ROOT, "doc");
@@ -126,8 +126,8 @@ function installPreCommitHook() {
   }
 
   const preCommitPath = path.join(hooksDir, "pre-commit");
-  const indexScript = `if [ -f doc/generate-index.py ]; then
-  python3 doc/generate-index.py doc 2>/dev/null || echo "openclew: index generation failed"
+  const indexScript = `if command -v npx >/dev/null 2>&1; then
+  npx --yes openclew index 2>/dev/null || echo "openclew: index generation failed"
   git add doc/_INDEX.md 2>/dev/null
 fi`;
 
@@ -168,26 +168,19 @@ function updateGitignore() {
   }
 }
 
-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/");
+function cleanupLegacyPython() {
+  // Remove legacy generate-index.py if present (replaced by JS-native index-gen)
+  const legacyScript = path.join(DOC_DIR, "generate-index.py");
+  if (fs.existsSync(legacyScript)) {
+    fs.unlinkSync(legacyScript);
+    console.log("  Removed legacy doc/generate-index.py (now JS-native)");
     return true;
   }
-
-  console.log("  generate-index.py not found in package — skipping");
+  console.log("  No legacy Python script to clean up");
   return false;
 }
 
-function createDocs() {
+function createDocs(entryPointPath) {
   // Guide — always created
   const guidePath = path.join(DOC_DIR, "_USING_OPENCLEW.md");
   if (!fs.existsSync(guidePath)) {
@@ -197,11 +190,30 @@ function createDocs() {
     console.log("  doc/_USING_OPENCLEW.md already exists");
   }
 
-  // Example refdoc
+  // Framework integration guide
+  const frameworkPath = path.join(DOC_DIR, "_OPENCLEW_FRAMEWORK_INTEGRATION.md");
+  if (!fs.existsSync(frameworkPath)) {
+    fs.writeFileSync(frameworkPath, frameworkIntegrationContent(), "utf-8");
+    console.log("  Created doc/_OPENCLEW_FRAMEWORK_INTEGRATION.md (framework integration guide)");
+  } else {
+    console.log("  doc/_OPENCLEW_FRAMEWORK_INTEGRATION.md already exists");
+  }
+
+  // Architecture refdoc — seeded from existing instruction file if available
   const examplePath = path.join(DOC_DIR, "_ARCHITECTURE.md");
   if (!fs.existsSync(examplePath)) {
-    fs.writeFileSync(examplePath, exampleRefdocContent(), "utf-8");
-    console.log("  Created doc/_ARCHITECTURE.md (example refdoc)");
+    let existingInstructions = null;
+    if (entryPointPath && fs.existsSync(entryPointPath)) {
+      try {
+        existingInstructions = fs.readFileSync(entryPointPath, "utf-8");
+      } catch {}
+    }
+    fs.writeFileSync(examplePath, exampleRefdocContent(existingInstructions), "utf-8");
+    if (existingInstructions) {
+      console.log("  Created doc/_ARCHITECTURE.md (seeded from instruction file)");
+    } else {
+      console.log("  Created doc/_ARCHITECTURE.md (template)");
+    }
   } else {
     console.log("  doc/_ARCHITECTURE.md already exists");
   }
@@ -217,15 +229,66 @@ function createDocs() {
 }
 
 function runIndexGenerator() {
-  const indexScript = path.join(DOC_DIR, "generate-index.py");
-  if (!fs.existsSync(indexScript)) return;
+  if (!fs.existsSync(DOC_DIR)) 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)");
+    const { writeIndex } = require("./index-gen");
+    const { refdocs, logs } = writeIndex(DOC_DIR);
+    console.log(`  Generated doc/_INDEX.md (${refdocs} refdocs, ${logs} logs)`);
+  } catch (err) {
+    console.log(`  Could not generate index: ${err.message}`);
+  }
+}
+
+function installSlashCommands() {
+  const home = process.env.HOME || process.env.USERPROFILE;
+  if (!home) {
+    console.log("  Cannot determine home directory — skipping");
+    return;
+  }
+
+  const claudeCommandsDir = path.join(home, ".claude", "commands");
+  if (!fs.existsSync(path.join(home, ".claude"))) {
+    console.log("  No ~/.claude/ found (Claude Code not installed) — skipping");
+    return;
+  }
+
+  if (!fs.existsSync(claudeCommandsDir)) {
+    fs.mkdirSync(claudeCommandsDir, { recursive: true });
+  }
+
+  // Find commands/ dir relative to this package
+  const pkgCommandsDir = path.join(__dirname, "..", "commands");
+  if (!fs.existsSync(pkgCommandsDir)) {
+    console.log("  No commands/ directory in package — skipping");
+    return;
+  }
+
+  const MARKER = "<!-- openclew-managed -->";
+  const files = fs.readdirSync(pkgCommandsDir).filter((f) => f.endsWith(".md"));
+  let installed = 0;
+
+  for (const file of files) {
+    const dest = path.join(claudeCommandsDir, file);
+
+    // Only overwrite if file has the managed marker (or doesn't exist)
+    if (fs.existsSync(dest)) {
+      const existing = fs.readFileSync(dest, "utf-8");
+      if (!existing.includes(MARKER)) {
+        console.log(`  Skipped ${file} (user-modified)`);
+        continue;
+      }
+    }
+
+    fs.copyFileSync(path.join(pkgCommandsDir, file), dest);
+    installed++;
+  }
+
+  if (installed > 0) {
+    console.log(`  Installed ${installed} slash command(s) → ~/.claude/commands/`);
+    console.log("  Available: /oc-checkout, /oc-search, /oc-init, /oc-status");
+  } else {
+    console.log("  Slash commands already up to date");
   }
 }
 
@@ -240,9 +303,9 @@ async function main() {
   console.log("\n2. Gitignore");
   updateGitignore();
 
-  // Step 3: Copy index generator
+  // Step 3: Cleanup legacy Python (if upgrading from older version)
   console.log("\n3. Index generator");
-  copyGenerateIndex();
+  cleanupLegacyPython();
 
   // Step 4: Entry point
   console.log("\n4. Entry point");
@@ -273,12 +336,21 @@ async function main() {
 
   // Step 6: Docs
   console.log("\n6. Docs");
-  createDocs();
+  createDocs(entryPoint ? entryPoint.fullPath : null);
 
   // Step 7: Generate index
   console.log("\n7. Index");
   runIndexGenerator();
 
+  // Step 8: Install Claude Code slash commands
+  const noCommands = args.includes("--no-commands");
+  console.log("\n8. Slash commands");
+  if (noCommands) {
+    console.log("  Skipping (--no-commands)");
+  } else {
+    installSlashCommands();
+  }
+
   // Done
   console.log("\n─── Ready ───\n");
   if (entryPoint) {

package/lib/inject.js

@@ -7,17 +7,27 @@ const fs = require("fs");
 const OPENCLEW_BLOCK = `
 ## Project knowledge (openclew)
 
-This file is the **entry point** for project documentation.
+This project uses \`doc/\` as its knowledge base. Before starting any task:
 
-**Doc-first rule:** before any task, read \`doc/_INDEX.md\` to find docs related to the task. Read them before exploring code.
+1. **Read \`doc/_INDEX.md\`** — it lists all available docs with a one-line summary each
+2. **Pick your reference doc(s)** — choose one or more docs relevant to what you're about to do
+3. **Read them** (L1 for relevance, L2 for context) — then start working
+4. **No matching doc?** — propose creating a refdoc with \`npx openclew new "Title"\` before starting
 
-Two types of docs in \`doc/\`:
-- **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
+If a doc contains placeholder comments (\`<!-- ... -->\`), fill them in based on what you observe in the code. This is expected — the docs are meant to be written by you.
 
-Each doc has 3 levels: **L1** (metadata — read first to decide relevance) → **L2** (summary) → **L3** (full details, only when needed).
+Two types of docs:
+- **Refdocs** (\`doc/_*.md\`) — architecture, conventions, decisions (evolve over time)
+- **Logs** (\`doc/log/YYYY-MM-DD_*.md\`) — frozen facts from past sessions
 
-**Creating docs:** when a decision, convention, or significant event needs to be captured, create the file directly following the format in \`doc/_USING_OPENCLEW.md\`.
+Each doc has 3 levels: **L1** (subject + brief — 1 line) → **L2** (summary) → **L3** (full details, only when needed).
+
+**Session commands** (user asks in chat, you run):
+- "peek" → \`npx openclew peek\` (list instruction file + all refdocs)
+- "checkout" → \`npx openclew checkout\` (end-of-session summary + log)
+- "new doc about X" → \`npx openclew new "X"\` (create refdoc)
+- "search X" → \`npx openclew search "X"\` (search docs)
+- "doc status" → \`npx openclew status\` (health dashboard)
 `.trim();
 
 const MARKER_START = "<!-- openclew_START -->";