@kevin0181/memoc 1.0.8 → 1.1.2

package/README.md

@@ -4,15 +4,18 @@
 
 Scaffolds a Markdown-based project memory into any codebase. Works with Claude Code, Codex, Cursor, Windsurf, GitHub Copilot, and Gemini CLI.
 
-## Quick Start
-
+## Quick Start
+
 ```bash
 npx @kevin0181/memoc init
+
+# Upgrade memoc in this project without deleting existing memory
+npx @kevin0181/memoc@latest upgrade
 ```
 
 Run inside your project directory. Detects your stack automatically and generates everything agents need.
 
-`init` also creates PATH helpers so agents can keep using memoc even when the global/npm bin is not on PATH. It installs a `memoc` launcher into a writable directory already on the current PATH when possible, then also installs a user-local launcher and registers that launcher directory on Windows, macOS, and Linux.
+`init` also creates project-local PATH helpers so agents can keep using memoc even when the global/npm bin is not on PATH.
 
 ```bash
 # PowerShell
@@ -22,9 +25,45 @@ Run inside your project directory. Detects your stack automatically and generate
 . ./.memoc/env.sh
 ```
 
-Agents are instructed to try commands in this order: `memoc <command>`, `.\.memoc\bin\memoc.cmd <command>` on Windows or `.memoc/bin/memoc <command>` in sh, then `npx @kevin0181/memoc <command>`.
-
----
+Agents are instructed to use the project-local wrapper if PATH fails:
+
+```bash
+# Windows
+.\.memoc\bin\memoc.cmd summary
+
+# macOS / Linux
+.memoc/bin/memoc summary
+```
+
+---
+
+## Ask An Agent To Install
+
+If you are giving this repo or npm package to an AI coding agent, use a prompt like:
+
+```text
+Install memoc in this project and run init.
+Use the npm package only. Run `npx @kevin0181/memoc@latest init`
+from this project's root. Do not clone the GitHub repository into this project.
+If npm/npx is missing, stop and ask the user to install Node.js LTS with npm first.
+After init, verify with the project-local wrapper:
+Windows: .\.memoc\bin\memoc.cmd summary
+macOS/Linux: .memoc/bin/memoc summary
+```
+
+Agent install checklist:
+
+1. Run `node --version` and `npm --version`. If either fails, ask the user to install Node.js LTS with npm first.
+2. Run `npx @kevin0181/memoc@latest init` from the target project root.
+3. Do not clone this GitHub repository into the target project. Do not download the repo ZIP as an installer.
+4. `.claude/settings.json` is intentionally generated for the Claude Code Stop hook; keep or commit it only if the project wants that hook.
+5. After init, do not depend on global PATH. Use the project-local wrapper when needed:
+   - Windows: `.\.memoc\bin\memoc.cmd <command>`
+   - macOS/Linux: `.memoc/bin/memoc <command>`
+
+If `node --version` or `npm --version` fails, memoc cannot be installed yet. Install Node.js LTS with npm first, then repeat the steps above.
+
+---
 
 ## The Problem
 
@@ -46,13 +85,13 @@ npx @kevin0181/memoc update
 # Print current status in ~10 lines
 npx @kevin0181/memoc summary
 
-# Search memory/agent docs first (token-efficient)
-npx @kevin0181/memoc search "auth"
-npx @kevin0181/memoc search "auth" --snippets --limit 5
-
-# Search project source/text files only when memory is not enough
-npx @kevin0181/memoc grep "GetParticles"
-npx @kevin0181/memoc grep "GetParticles" --snippets --limit 5
+# Search memory/agent docs first (token-efficient)
+npx @kevin0181/memoc search "auth"
+npx @kevin0181/memoc search "auth" --snippets --limit 5
+
+# Search project source/text files only when memory is not enough
+npx @kevin0181/memoc grep "GetParticles"
+npx @kevin0181/memoc grep "GetParticles" --snippets --limit 5
 
 # Estimate token cost of current memory files
 npx @kevin0181/memoc tokens
@@ -69,7 +108,38 @@ npx @kevin0181/memoc add gemini
 
 ---
 
-## What Gets Created
+## Upgrade Existing Projects
+
+memoc never auto-updates itself. Upgrade only when you choose to run:
+
+```bash
+npx @kevin0181/memoc@latest upgrade
+```
+
+Run it from the project root. It preserves existing project memory, including:
+
+- `.memoc/session-summary.md`
+- `.memoc/02-current-project-state.md` human-written sections
+- `.memoc/03-decisions.md`
+- `.memoc/04-handoff.md`
+- `.memoc/06-project-rules.md`
+- `.memoc/log.md`
+- `.memoc/systems/`
+- `.memoc/wiki/`
+
+It refreshes the managed blocks, project-local wrappers, runtime copy, PATH helpers, and missing template files. If `memoc` is not on PATH after upgrading, keep using:
+
+```bash
+# Windows
+.\.memoc\bin\memoc.cmd summary
+
+# macOS / Linux
+.memoc/bin/memoc summary
+```
+
+---
+
+## What Gets Created
 
 ```
 CLAUDE.md                                    ← Claude Code entry point (auto-loaded)
@@ -77,11 +147,11 @@ AGENTS.md                                    ← Codex entry point (auto-loaded)
 llms.txt                                     ← LLM-facing project map
 .claude/settings.json                        ← Claude Code Stop hook
 
-.memoc/
-  bin/memoc                                  ← project-local wrapper for PATH fallback
-  env.ps1 · env.sh                           ← shell helpers that prepend .memoc/bin to PATH
-  session-summary.md                         ← Only required startup read (~150 tokens)
-  02-current-project-state.md               ← Status, open tasks, commands
+.memoc/
+  bin/memoc                                  ← project-local wrapper for PATH fallback
+  env.ps1 · env.sh                           ← shell helpers that prepend .memoc/bin to PATH
+  session-summary.md                         ← Only required startup read (~150 tokens)
+  02-current-project-state.md               ← Status, open tasks, commands
   03-decisions.md                            ← Durable decision log
   04-handoff.md                              ← Resume context, verified/unverified
   06-project-rules.md                        ← User preferences