openclew 0.3.0 → 0.4.0

package/LICENSE

@@ -1,21 +1,190 @@
-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.
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to the Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by the Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding any notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   Copyright 2026 R.AlphA
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -112,6 +112,31 @@ Next session, your agent reads the index, finds the doc, has the context. No re-
 
 The index auto-regenerates on every commit. Never edit it manually.
 
+### CLI commands
+
+```bash
+openclew init                    # Set up openclew in your project
+openclew add ref <title>         # Create a refdoc (evolves with the project)
+openclew add log <title>         # Create a session log (frozen facts)
+openclew search <query>          # Search docs by keyword
+openclew checkout                # End-of-session summary
+openclew status                  # Documentation health dashboard
+openclew mcp                     # Start MCP server (stdio JSON-RPC)
+```
+
+### Claude Code slash commands
+
+`openclew init` installs 4 slash commands into Claude Code:
+
+| Command | What it does |
+|---------|-------------|
+| `/oc-checkout` | End-of-session summary — review actions, create log, commit |
+| `/oc-search` | Search project docs by keyword |
+| `/oc-init` | Set up openclew in the current project |
+| `/oc-status` | Documentation health dashboard |
+
+These work like any Claude Code slash command — type `/oc-` and pick one. No `npx` needed.
+
 <details>
 <summary><b>Manual setup</b> — if you prefer not to use the CLI</summary>
 
@@ -180,7 +205,15 @@ doc/
 
 **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.
+**What the CLI does for you:**
+- Detects your instruction file (CLAUDE.md, .cursorrules, AGENTS.md, copilot-instructions...)
+- Injects a knowledge block that teaches your agent about the doc structure
+- Generates and regenerates the index on every commit (pre-commit hook)
+- Searches docs by keyword with weighted scoring (`openclew search`)
+- Exposes docs via MCP server for tool-aware agents (`openclew mcp`)
+- Produces a session summary at end of work (`openclew checkout`)
+
+**What you get:** plain Markdown files. Git-versioned, diffable, reviewable in PRs. Zero npm dependencies — Node 16+ is all you need. No lock-in: if you stop using the CLI, the docs are still useful — to humans and agents alike.
 
 ---
 
@@ -202,4 +235,4 @@ doc/
 
 ## License
 
-MIT — use it however you want.
+Apache 2.0 — use it however you want. Patent protection included.

package/bin/openclew.js

@@ -13,6 +13,7 @@ Usage:
   openclew add ref <title>         Create a refdoc (evolves with the project)
   openclew add log <title>         Create a session log (frozen facts)
   openclew search <query>          Search docs by keyword
+  openclew peek                    List instruction file + all refdocs
   openclew checkout                End-of-session summary
 
 Run 'openclew help --all' for advanced commands.
@@ -27,6 +28,7 @@ Usage:
   openclew add ref <title>         Create a refdoc (evolves with the project)
   openclew add log <title>         Create a session log (frozen facts)
   openclew search <query>          Search docs by keyword
+  openclew peek                    List instruction file + all refdocs
   openclew checkout                End-of-session summary
 
 Advanced:
@@ -67,6 +69,7 @@ const commands = {
   log: () => require("../lib/new-log"),
   checkout: () => require("../lib/checkout"),
   search: () => require("../lib/search"),
+  peek: () => require("../lib/peek"),
   status: () => require("../lib/status"),
   index: () => require("../lib/index-gen"),
   mcp: () => require("../lib/mcp-server"),

package/commands/oc-checkout.md

@@ -0,0 +1,134 @@
+<!-- openclew-managed -->
+# oc-checkout — End-of-session summary
+
+Generates a structured summary of the session and persists it as a log.
+
+**Usage:** `/oc-checkout` (no arguments, uses the current project)
+
+## Key principle
+
+**Commits happen AFTER the checkout**, never during. This allows including logs created during checkout in the same commit.
+
+## Status emojis
+
+| Emoji | Column | Meaning |
+|-------|--------|---------|
+| ✅    | Status | Done |
+| 🚧    | Status | In progress / partial |
+| ❌    | Status | Not done |
+| 📗    | Doc    | Documented (log, refdoc, or instruction file) |
+| 📕    | Doc    | Not documented |
+| 🟢    | Commit | Already committed |
+| 🟡    | Commit | To be committed |
+
+## Sequence
+
+### Phase 1: Collection (silent)
+
+Execute silently — go straight to the Phase 2 table:
+1. Run `npx openclew checkout` to collect git activity and display the CLI summary
+2. List session actions (features, bugs, refactors...)
+3. Check which files are documented (`doc/log/*.md`, `doc/_*.md`)
+4. Check git status of each file (committed or not)
+
+### Phase 2: Summary table
+
+Display the recap table for validation.
+
+**Format:**
+- Box-drawing (no Markdown pipes)
+- **Isolated emojis** in dedicated mini-columns (never emoji + text in the same cell)
+- Emoji columns: **5 chars wide** (`─────`) with **2 spaces after emoji** (`│ ✅  │`)
+- Action column: **max 50 chars** (rephrase/abbreviate if needed, never truncate)
+- No separator `├───┤` between data rows, only after the header
+
+**Example:**
+```
+┌─────┬──────────────────────────────────────┬─────┬────────────────────────┬─────┐
+│ Sta │ Action                               │ Doc │ File                   │Comm.│
+├─────┼──────────────────────────────────────┼─────┼────────────────────────┼─────┤
+│ ✅  │ Feature: Auth middleware refactor    │ 📗  │ 2026-01-15_auth.md     │ 🟢  │
+│ 🚧  │ Fix: Table alignment                │ 📕  │ Not documented         │ 🟡  │
+└─────┴──────────────────────────────────────┴─────┴────────────────────────┴─────┘
+```
+
+### Phase 3: Refdocs to update?
+
+1. List refdocs: all `doc/_*.md` files (excluding `_INDEX.md`) + project instruction file (CLAUDE.md, AGENTS.md, etc.)
+2. Filter those related to session actions (by name only — don't read yet)
+3. For each related doc: read and assign status:
+   - ☑️ No update needed (verified, up to date)
+   - ✅ Already updated during session
+   - 📒 Needs update (proposed in Phase 4)
+4. **Instruction file**: always evaluated. Flag 📒 if:
+   - New refdoc created during session (needs reference)
+   - Useful info discovered (pitfall, convention, command)
+   - Stale context (abandoned topic, modified rule)
+   - File missing (needs creation)
+5. Display all related docs with status:
+
+```
+📚 Refdocs:
+   ✅ _AUTH_DESIGN.md       — updated (session section)
+   ☑️ _ARCHITECTURE.md      — verified, up to date
+   📒 _INSTALL_GUIDE.md     — new deploy step to document
+   📒 CLAUDE.md             — new pitfall discovered
+```
+
+### Phase 4: Proposed actions (grouped)
+
+Display all actions together:
+
+```
+─── Proposed actions ───
+
+1. [ ] Create log for "Fix: Description" → `2026-01-15_topic.md`
+2. [ ] Update CLAUDE.md (modified context)
+
+Approve actions? (yes/no/modify)
+```
+
+- Wait for user validation
+- If "modify": user indicates changes, adapt, re-validate
+- Execute validated actions (create logs, updates)
+
+### Phase 5: Commits (AFTER everything else)
+
+Execute directly after action validation:
+
+1. Check `git status` for all files to commit
+2. Execute commit(s)
+3. Logs created in Phase 4 are included
+4. Display result
+
+## Closing message
+
+**Mandatory at the end of checkout.** Displayed after commits.
+
+```
+─── Summary ───
+1. Concrete fact #1 (short sentence)
+2. Concrete fact #2
+
+✅📗🟢  Feature: Description              →  file.md
+🚧📕🟡  Fix: Description                  →  (not documented)
+
+─── How to test ───
+• manual action or command → expected result
+
+─── Next steps ───
+⏭️📗 Test the new feature              →  CLAUDE.md TODO
+⏭️📕 Explore WebSocket option
+
+═══════════════════════════════════════
+🏁 Session complete
+```
+
+**Compact format — 3 emojis concatenated:**
+- Position 1: status (✅ done / 🚧 in progress / ❌ not done)
+- Position 2: documentation (📗 yes / 📕 no)
+- Position 3: commit (🟢 yes / 🟡 no)
+
+**Closing rule:**
+- `🏁 Session complete`: only if all actions are ✅📗🟢
+- Otherwise: `⏸️ Session incomplete` and list what remains

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/init.js

@@ -240,6 +240,58 @@ function runIndexGenerator() {
   }
 }
 
+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");
+  }
+}
+
 async function main() {
   console.log("\nopenclew init\n");
 
@@ -290,6 +342,15 @@ async function main() {
   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

@@ -23,6 +23,7 @@ Two types of docs:
 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)

package/lib/peek.js

@@ -0,0 +1,166 @@
+/**
+ * openclew peek — list instruction file + all refdocs (doc/ and project-wide)
+ *
+ * Discovery tool: shows what knowledge exists before starting work.
+ * Zero dependencies — Node 16+ standard library only.
+ */
+
+const fs = require("fs");
+const path = require("path");
+const { collectDocs } = require("./search");
+
+/**
+ * Recursively find _*.md files in a directory tree.
+ * Excludes common non-doc directories.
+ *
+ * @param {string} dir - Directory to scan
+ * @param {string[]} excludePaths - Absolute paths to exclude
+ * @returns {string[]} Sorted list of absolute file paths
+ */
+function findRefdocsRecursive(dir, excludePaths = []) {
+  const results = [];
+  const EXCLUDE_DIRS = new Set([
+    ".git",
+    "node_modules",
+    "_archive",
+    "old",
+    ".Rproj.user",
+    "log",
+    "notes",
+    "verify_logs",
+  ]);
+
+  function walk(current) {
+    let entries;
+    try {
+      entries = fs.readdirSync(current, { withFileTypes: true });
+    } catch {
+      return;
+    }
+
+    for (const entry of entries) {
+      const fullPath = path.join(current, entry.name);
+
+      if (entry.isDirectory()) {
+        if (EXCLUDE_DIRS.has(entry.name)) continue;
+        if (excludePaths.some((ex) => fullPath === ex || fullPath.startsWith(ex + path.sep))) continue;
+        walk(fullPath);
+      } else if (
+        entry.isFile() &&
+        entry.name.startsWith("_") &&
+        entry.name.endsWith(".md") &&
+        entry.name !== "_INDEX.md"
+      ) {
+        results.push(fullPath);
+      }
+    }
+  }
+
+  walk(dir);
+  return results.sort();
+}
+
+/**
+ * Run peek for a project.
+ *
+ * @param {string} projectRoot - Absolute path to project root
+ * @returns {{ instructionFile: string|null, docRefdocs: Array, otherRefdocs: string[] }}
+ */
+function peek(projectRoot) {
+  const docDir = path.join(projectRoot, "doc");
+
+  // Instruction file (CLAUDE.md or AGENTS.md)
+  let instructionFile = null;
+  for (const name of ["CLAUDE.md", "AGENTS.md"]) {
+    const p = path.join(projectRoot, name);
+    if (fs.existsSync(p)) {
+      instructionFile = p;
+      break;
+    }
+  }
+
+  // Refdocs in doc/ (with parsed metadata)
+  let docRefdocs = [];
+  if (fs.existsSync(docDir)) {
+    const docs = collectDocs(docDir);
+    docRefdocs = docs.filter((d) => d.kind === "refdoc");
+  }
+
+  // Refdocs outside doc/
+  const otherRefdocs = findRefdocsRecursive(projectRoot, [docDir]);
+
+  return { instructionFile, docRefdocs, otherRefdocs };
+}
+
+// ── CLI runner ──────────────────────────────────────────────────────
+
+function run() {
+  const projectRoot = process.cwd();
+  const result = peek(projectRoot);
+  const projectName = path.basename(projectRoot);
+
+  console.log(`\n${projectName}\n`);
+
+  // Instruction file
+  if (result.instructionFile) {
+    console.log(`Instruction file: ${path.basename(result.instructionFile)}`);
+  } else {
+    console.log("Instruction file: (none)");
+  }
+  console.log("");
+
+  // Doc refdocs
+  console.log(`Refdocs in doc/ (${result.docRefdocs.length}):`);
+  if (result.docRefdocs.length) {
+    for (const doc of result.docRefdocs) {
+      const name = path.basename(doc.filepath);
+      const subject = doc.meta.subject || "";
+      const status = doc.meta.status || "";
+      const statusTag = status ? ` [${status}]` : "";
+      if (subject) {
+        console.log(`  ${name} — ${subject}${statusTag}`);
+      } else {
+        console.log(`  ${name}${statusTag}`);
+      }
+    }
+  } else {
+    console.log("  (none)");
+  }
+  console.log("");
+
+  // Other refdocs
+  if (result.otherRefdocs.length) {
+    console.log(`Refdocs outside doc/ (${result.otherRefdocs.length}):`);
+    for (const filepath of result.otherRefdocs) {
+      const rel = path.relative(projectRoot, filepath);
+      console.log(`  ${rel}`);
+    }
+    console.log("");
+  }
+
+  // Subdirectories of doc/
+  const docDir = path.join(projectRoot, "doc");
+  if (fs.existsSync(docDir)) {
+    const SKIP = new Set(["log", "notes", "verify_logs", "_archive", "old"]);
+    const subdirs = fs
+      .readdirSync(docDir, { withFileTypes: true })
+      .filter((e) => e.isDirectory() && !SKIP.has(e.name))
+      .map((e) => e.name)
+      .sort();
+
+    if (subdirs.length) {
+      console.log("Subdirectories in doc/:");
+      for (const d of subdirs) {
+        console.log(`  ${d}/`);
+      }
+      console.log("");
+    }
+  }
+}
+
+module.exports = { peek, findRefdocsRecursive };
+
+const calledAsPeek = process.argv.includes("peek");
+if (require.main === module || calledAsPeek) {
+  run();
+}

package/package.json

@@ -1,26 +1,17 @@
 {
   "name": "openclew",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Long Life Memory for LLMs — structured project knowledge for AI agents and humans",
-  "license": "MIT",
+  "license": "Apache-2.0",
   "bin": {
     "openclew": "./bin/openclew.js"
   },
   "files": [
     "bin/",
-    "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",
+    "lib/",
+    "!lib/migrate.js",
     "templates/",
+    "commands/",
     "skills/",
     "README.md",
     "UPGRADING.md",

package/skills/{openclew-checkpoint → oc-checkpoint}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: openclew-checkpoint
+name: oc-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
 ---

package/skills/{openclew-init → oc-init}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: openclew-init
+name: oc-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
 ---

package/skills/{openclew-search → oc-search}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: openclew-search
+name: oc-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
 ---

package/templates/FORMAT.md

@@ -1,7 +1,7 @@
 # openclew document format
 
 > SSOT — this file defines the canonical format for all openclew documents.
-> Templates (`refdoc.md`, `log.md`), embedded templates (`lib/templates.js`), and parsers (`generate-index.py`, `lib/search.js`) must conform to this spec.
+> Templates (`refdoc.md`, `log.md`), embedded templates (`lib/templates.js`), and parsers (`lib/index-gen.js`, `lib/search.js`) must conform to this spec.
 
 ---
 
@@ -91,15 +91,16 @@ Between `<!-- L1_START -->` and `<!-- L1_END -->` markers. Two fields only:
 <!-- L1_START -->
 **subject:** Short title (< 60 chars)
 
-**doc_brief:** 1-2 sentences of **assertions** (what is true), not narration (what was done). Must be enough to decide if you need to read further.
+**doc_brief:** 1-2 sentences describing what was done and why, not what the document contains. Must be enough to decide if you need to read further.
 <!-- L1_END -->
 ```
 
 ### Rules
 
 - **subject** is the document's title. Keep it short and scannable.
-- **doc_brief** answers: "Should I read this?" Write **assertions** — state what is true, decided, or concluded. Don't narrate what was done. Quick test: remove "we investigated" / "we compared" — if the sentence collapses, rewrite it.
-  - Bad: "Investigated memory leak in worker pool. Profiled with pprof, tested several fixes."
+- **doc_brief** answers: "Should I read this?" Describe **what was done and why**, not what the document contains. Quick test: if it starts with "this document describes/presents/contains", it's meta — rewrite with concrete content.
+  - Bad (meta): "Configuration and usage of the authentication system for the web application."
+  - Bad (process without conclusion): "Investigated memory leak in worker pool. Profiled with pprof, tested several fixes."
   - Good: "Worker pool leaked memory via unclosed response bodies in retry path. Fixed with deferred close. Steady at 120MB under load."
 - Both fields use `**bold_key:**` syntax (not YAML `key: value`).
 - No other fields in L1. All metadata lives on line 1.
@@ -178,7 +179,7 @@ Between `<!-- L3_START -->` and `<!-- L3_END -->` markers. Starts with `# L3 - D
 
 ## Parser compatibility
 
-The `generate-index.py` parser extracts:
+The `lib/index-gen.js` parser (via `lib/search.js`) extracts:
 1. **Line 1 metadata**: splits on ` · `, parses `key: value` pairs
 2. **L1 fields**: regex for `**subject:**` and `**doc_brief:**` between L1 markers