From b7997c5fb6327f89750dc63f5ddb479c811ae970 Mon Sep 17 00:00:00 2001
From: papperrollinggery <100415055+papperrollinggery@users.noreply.github.com>
Date: Wed, 20 May 2026 23:33:49 +0800
Subject: [PATCH] docs: prepare beta release

---
 README.md                 | 18 ++++++++--
 README_CN.md              | 18 ++++++++--
 docs/INSTALL.md           | 76 +++++++++++++++++++++++++++++++++++++++
 docs/PRIVACY.md           | 37 +++++++++++++++++++
 docs/RELEASE_CHECKLIST.md | 57 +++++++++++++++++++++++++++++
 docs/USE_CASES.md         | 66 ++++++++++++++++++++++++++++++++++
 package.json              |  4 +++
 scripts/audit-public.js   |  8 +++++
 8 files changed, 280 insertions(+), 4 deletions(-)
 create mode 100644 docs/INSTALL.md
 create mode 100644 docs/PRIVACY.md
 create mode 100644 docs/RELEASE_CHECKLIST.md
 create mode 100644 docs/USE_CASES.md

diff --git a/README.md b/README.md
index acbf1e5..96bd306 100644
--- a/README.md
+++ b/README.md
@@ -10,9 +10,11 @@ You installed hundreds of AI skills, commands, plugins, and local rules. You rem
 
 ## Install
 
+Beta channel:
+
 ```bash
-npx --yes lazybrain quickstart
-npm install -g lazybrain
+npm install -g lazybrain@beta
+lb quickstart
 lb "review this PR for security issues"
 ```
 
@@ -24,6 +26,8 @@ npm run build
 node dist/bin/lazybrain.js quickstart
 ```
 
+See [docs/INSTALL.md](docs/INSTALL.md) for MCP setup, local capability paths, and source checkout usage.
+
 ## What It Does
 
 ```bash
@@ -57,6 +61,8 @@ LazyBrain scans or indexes local capability files for:
 
 Default scan paths include Claude skills/commands, project commands, Cursor/Windsurf/Cline rule files, `.skillshub`, `.codex/skills`, and `.agents/skills`.
 
+LazyBrain is local-first. It scans local capability metadata and writes local cache/history files; it does not call an LLM on the hot path and does not upload scanned files. See [docs/PRIVACY.md](docs/PRIVACY.md).
+
 ## Orchestration
 
 `lb orchestrate` upgrades a single task into an ordered work plan:
@@ -140,6 +146,14 @@ The smallest useful PR is one trigger phrase plus one golden-set case:
 
 Useful contribution areas: trigger phrases, combo templates, orchestration rules, scanner coverage, and benchmark cases.
 
+## User Scenarios
+
+See [docs/USE_CASES.md](docs/USE_CASES.md) for supported beta workflows and examples.
+
+## Release Readiness
+
+See [docs/RELEASE_CHECKLIST.md](docs/RELEASE_CHECKLIST.md) before publishing a beta or stable release.
+
 ## License
 
 AGPL-3.0.
diff --git a/README_CN.md b/README_CN.md
index ca1fdec..2f6b1a1 100644
--- a/README_CN.md
+++ b/README_CN.md
@@ -10,9 +10,11 @@
 
 ## 安装
 
+Beta channel：
+
 ```bash
-npx --yes lazybrain quickstart
-npm install -g lazybrain
+npm install -g lazybrain@beta
+lb quickstart
 lb "review this PR for security issues"
 ```
 
@@ -24,6 +26,8 @@ npm run build
 node dist/bin/lazybrain.js quickstart
 ```
 
+MCP 配置、本地 capability 路径和源码运行方式见 [docs/INSTALL.md](docs/INSTALL.md)。
+
 ## 常用命令
 
 ```bash
@@ -57,6 +61,8 @@ LazyBrain 可以扫描或索引这些本地能力来源：
 
 默认覆盖 Claude skills/commands、项目 commands、Cursor/Windsurf/Cline 规则文件、`.skillshub`、`.codex/skills` 和 `.agents/skills`。
 
+LazyBrain 是 local-first。它扫描本地 capability metadata，写入本地 cache/history；核心路径不调用 LLM，也不会上传扫描到的文件。隐私边界见 [docs/PRIVACY.md](docs/PRIVACY.md)。
+
 ## 编排能力
 
 `lb orchestrate` 会把一句任务升级成有顺序的执行计划：
@@ -140,6 +146,14 @@ Verification: npm run audit:public && npm pack --dry-run --json
 
 适合贡献的方向：触发词、combo 模板、编排规则、scanner 覆盖、benchmark cases。
 
+## 使用场景
+
+Beta 阶段支持的真实用户场景见 [docs/USE_CASES.md](docs/USE_CASES.md)。
+
+## 发布检查
+
+发布 beta 或 stable 前先跑 [docs/RELEASE_CHECKLIST.md](docs/RELEASE_CHECKLIST.md)。
+
 ## License
 
 AGPL-3.0.
diff --git a/docs/INSTALL.md b/docs/INSTALL.md
new file mode 100644
index 0000000..c34b511
--- /dev/null
+++ b/docs/INSTALL.md
@@ -0,0 +1,76 @@
+# Install LazyBrain
+
+LazyBrain is a local-first capability router for AI agent tools. It runs on Node.js 18 or newer.
+
+## Beta Install
+
+```bash
+npm install -g lazybrain@beta
+lb quickstart
+lb "review this PR for security issues"
+```
+
+If the beta package is not published yet, install from a checkout:
+
+```bash
+git clone https://github.com/papperrollinggery/lazy-brain.git
+cd lazy-brain
+npm ci
+npm run build
+node dist/bin/lazybrain.js quickstart
+node dist/bin/lazybrain.js "review this PR for security issues"
+```
+
+## MCP Setup
+
+After global install:
+
+```json
+{
+  "mcpServers": {
+    "lazybrain": {
+      "command": "lazybrain-mcp",
+      "args": []
+    }
+  }
+}
+```
+
+From a source checkout:
+
+```json
+{
+  "mcpServers": {
+    "lazybrain": {
+      "command": "node",
+      "args": ["/absolute/path/to/lazy-brain/dist/bin/mcp.js"]
+    }
+  }
+}
+```
+
+## Local Capability Sources
+
+`lb quickstart` scans common local agent capability locations:
+
+- `~/.claude/skills`
+- `~/.claude/commands`
+- `~/.codex/skills`
+- `~/.agents/skills`
+- `~/.skillshub`
+- project `.claude/commands`
+- Cursor, Windsurf, Cline, and OpenCode rule files
+
+Empty machines still work. LazyBrain includes a built-in capability set, so a first run without local skills can still route common tasks.
+
+## Smoke Test
+
+```bash
+lb --version
+lb quickstart
+lb "review this PR for security issues"
+lb orchestrate "deploy payment feature"
+lazybrain-mcp
+```
+
+Expected result: commands exit successfully and route to concrete capabilities such as `/security-review`, `/code-review`, or `/ship`.
diff --git a/docs/PRIVACY.md b/docs/PRIVACY.md
new file mode 100644
index 0000000..cc1942e
--- /dev/null
+++ b/docs/PRIVACY.md
@@ -0,0 +1,37 @@
+# Privacy
+
+LazyBrain is local-first.
+
+## What It Reads
+
+LazyBrain reads local capability metadata so it can route plain-language tasks:
+
+- skill names, descriptions, triggers, and examples
+- command names and local rule metadata
+- local usage history written by LazyBrain
+- optional user rules in `~/.lazybrain/rules.yaml`
+
+Default scan paths include Claude, Codex, Cursor, Windsurf, Cline, OpenCode, `.skillshub`, `.codex/skills`, and `.agents/skills`.
+
+## What It Writes
+
+LazyBrain writes local cache and history files under the user's home directory. These files support faster routing, stats, discovery, and learned workflow signals.
+
+## What It Does Not Do
+
+- No runtime LLM call on the hot path.
+- No upload of scanned capability files.
+- No cloud account is required.
+- No telemetry is sent by LazyBrain.
+- No credentials are required for normal CLI routing.
+
+## Sensitive Data
+
+Do not put secrets in skill descriptions, command files, examples, or rules. LazyBrain treats local capability text as routing metadata. If private content exists in those files, it may appear in local cache or local command output.
+
+Before publishing a package, run:
+
+```bash
+npm run audit:public
+npm pack --dry-run --json
+```
diff --git a/docs/RELEASE_CHECKLIST.md b/docs/RELEASE_CHECKLIST.md
new file mode 100644
index 0000000..b76fa13
--- /dev/null
+++ b/docs/RELEASE_CHECKLIST.md
@@ -0,0 +1,57 @@
+# Release Checklist
+
+## Beta Release
+
+Run from a clean checkout:
+
+```bash
+npm ci
+npm run build
+npm run lint
+npm test
+npm run audit:public
+npm pack --dry-run --json
+```
+
+Install smoke:
+
+```bash
+npm pack --json
+tmpdir=$(mktemp -d)
+cd "$tmpdir"
+npm init -y
+npm install /absolute/path/to/lazybrain-2.0.0.tgz
+./node_modules/.bin/lb --version
+./node_modules/.bin/lb quickstart
+./node_modules/.bin/lb "review this PR for security issues"
+./node_modules/.bin/lb orchestrate "deploy payment feature"
+```
+
+Publish beta:
+
+```bash
+npm publish --tag beta
+npm view lazybrain dist-tags --json
+npx --yes lazybrain@beta quickstart
+```
+
+## Required Release Notes
+
+Include:
+
+- beta status
+- Node.js 18+ requirement
+- local-first privacy boundary
+- no runtime LLM call on the hot path
+- supported command surfaces: `lb`, `lazybrain`, `lazybrain-mcp`
+- known limits: no hosted dashboard, no automatic execution, no cross-machine sync
+
+## Stable Release Gate
+
+Do not promote beta to latest until:
+
+- at least 3 real users complete install and first route
+- at least 30 real user queries are added to golden or smoke coverage
+- README install command works from npm registry
+- privacy doc and package contents have been reviewed
+- GitHub Release notes are published
diff --git a/docs/USE_CASES.md b/docs/USE_CASES.md
new file mode 100644
index 0000000..de8c40f
--- /dev/null
+++ b/docs/USE_CASES.md
@@ -0,0 +1,66 @@
+# LazyBrain Use Cases
+
+## 1. Find the Right Capability
+
+```bash
+lb "review this PR for security issues"
+```
+
+Expected result: LazyBrain recommends `/security-review` and nearby alternatives.
+
+Use this when the user has many skills or slash commands and does not remember the exact name.
+
+## 2. Turn a Task Into an Execution Plan
+
+```bash
+lb orchestrate "deploy payment feature"
+```
+
+Expected result: LazyBrain returns an ordered sequence such as security review, TDD, code review, and ship.
+
+Use this for risky tasks where ordering matters.
+
+## 3. Pick a Reusable Workflow
+
+```bash
+lb combo "deploy new feature to production"
+```
+
+Expected result: LazyBrain returns a reusable workflow template plus verification commands.
+
+Use this for repeated work such as releases, incident response, audits, and documentation.
+
+## 4. Discover Underused Local Tools
+
+```bash
+lb discover
+lb stats
+```
+
+Expected result: LazyBrain shows high-value local capabilities and usage patterns.
+
+Use this after installing many local skills or when a team wants to standardize how agent tools are used.
+
+## 5. Use LazyBrain From an Agent
+
+```bash
+lazybrain-mcp
+```
+
+Expected result: the stdio MCP server exposes routing and orchestration tools to an agent client.
+
+Use this when Claude, Codex, Cursor, or another MCP client needs deterministic capability selection.
+
+## Good Beta Fit
+
+- local AI power users
+- teams with many skills, prompts, rules, or commands
+- agent workflow authors
+- developers who want deterministic routing with no runtime LLM dependency
+
+## Not a Fit Yet
+
+- users who expect LazyBrain to execute every step automatically
+- users who need a hosted team dashboard
+- users who need cross-machine sync
+- users who need managed cloud telemetry or analytics
diff --git a/package.json b/package.json
index 3b9afac..744545b 100644
--- a/package.json
+++ b/package.json
@@ -20,6 +20,10 @@
   "files": [
     "dist",
     "docs/assets",
+    "docs/INSTALL.md",
+    "docs/PRIVACY.md",
+    "docs/RELEASE_CHECKLIST.md",
+    "docs/USE_CASES.md",
     "README_CN.md",
     "CHANGELOG.md"
   ],
diff --git a/scripts/audit-public.js b/scripts/audit-public.js
index 7d28f28..775acc2 100644
--- a/scripts/audit-public.js
+++ b/scripts/audit-public.js
@@ -40,6 +40,10 @@ function checkPack() {
     file === 'CHANGELOG.md' ||
     file === 'LICENSE' ||
     file === 'docs/assets/lazybrain-demo.svg' ||
+    file === 'docs/INSTALL.md' ||
+    file === 'docs/PRIVACY.md' ||
+    file === 'docs/RELEASE_CHECKLIST.md' ||
+    file === 'docs/USE_CASES.md' ||
     file.startsWith('dist/'));
   if (!allowed) {
     fail(`npm package includes unexpected files: ${files.filter(file =>
@@ -49,6 +53,10 @@ function checkPack() {
       file !== 'CHANGELOG.md' &&
       file !== 'LICENSE' &&
       file !== 'docs/assets/lazybrain-demo.svg' &&
+      file !== 'docs/INSTALL.md' &&
+      file !== 'docs/PRIVACY.md' &&
+      file !== 'docs/RELEASE_CHECKLIST.md' &&
+      file !== 'docs/USE_CASES.md' &&
       !file.startsWith('dist/')).join(', ')}`);
   }
   const required = ['dist/bin/lazybrain.js', 'dist/bin/mcp.js', 'dist/bin/hook.js', 'dist/index.js', 'dist/index.d.ts'];