flowmind 1.4.5 → 1.4.7

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # Changelog
 
+## [1.4.7] - 2026-06-30
+
+### Added
+- npm package now ships the demo assets and integration guide referenced by the README
+
+### Changed
+- Release packaging now excludes local promotion copy so community post drafts do not get published to npm
+- Demo setup now reads the package version dynamically instead of keeping a stale hardcoded value
+
+## [1.4.6] - 2026-06-30
+
+### Added
+- Portable demo scripts for skill listing, log audit, learning feedback, and JSON output replay from the repository root
+- Animated terminal walkthrough assets, including a VHS tape and generated demo GIF
+
+### Changed
+- Demo helpers now fall back to the local `node ./bin/flowmind.js` entrypoint when a global `flowmind` binary is unavailable
+- README and demo docs now expose the terminal walkthrough directly for GitHub and npm readers
+
 ## [1.4.5] - 2026-06-29
 
 ### Fixed

package/CONTRIBUTING.md

@@ -0,0 +1,236 @@
+# Contributing to FlowMind
+
+Thank you for your interest in contributing to FlowMind! 🎉
+
+## 🤝 Ways to Contribute
+
+- 🐛 **Report bugs** - Help us identify issues
+- 💡 **Suggest features** - Share your ideas
+- 📝 **Improve docs** - Make documentation better
+- 🛠️ **Add skills** - Create new capabilities
+- 🌍 **Translations** - Help localize
+- 🧪 **Write tests** - Improve quality
+
+## 🚀 Getting Started
+
+### 1. Fork & Clone
+
+```bash
+git clone https://github.com/your-username/flowmind.git
+cd flowmind
+```
+
+### 2. Install Dependencies
+
+```bash
+npm install
+```
+
+### 3. Create Branch
+
+```bash
+git checkout -b feature/your-feature-name
+```
+
+### 4. Make Changes
+
+Make your changes, following our coding standards.
+
+### 5. Test
+
+```bash
+npm test
+```
+
+### 6. Submit PR
+
+Push your changes and create a pull request.
+
+## 📝 Coding Standards
+
+### Code Style
+
+- Use ESLint for JavaScript
+- Follow Prettier formatting
+- Write meaningful commit messages
+
+### Commit Messages
+
+```
+<type>(<scope>): <description>
+
+[optional body]
+
+[optional footer]
+```
+
+Types:
+- `feat`: New feature
+- `fix`: Bug fix
+- `docs`: Documentation
+- `style`: Formatting
+- `refactor`: Code refactoring
+- `test`: Adding tests
+- `chore`: Maintenance
+
+### Testing
+
+- Write unit tests for new features
+- Ensure all tests pass
+- Aim for >80% coverage
+
+```bash
+npm test
+npm run test:coverage
+```
+
+## 🛠️ Creating Skills
+
+### Skill Structure
+
+```
+skills/
+└── your-skill/
+    ├── SKILL.md        # Skill definition
+    ├── index.js        # Implementation
+    └── tests/          # Tests
+```
+
+### Skill Definition (SKILL.md)
+
+```markdown
+---
+name: your-skill
+description: What this skill does
+metadata:
+  version: "1.0.0"
+  author: your-name
+  category: your-category
+---
+
+# Your Skill
+
+## Trigger Conditions
+When should this skill activate?
+
+## Features
+What does this skill do?
+
+## Examples
+How to use this skill?
+```
+
+### Skill Implementation (index.js)
+
+```javascript
+module.exports = {
+  name: 'your-skill',
+  version: '1.0.0',
+
+  canHandle(input, context) {
+    // Return true if this skill should handle the input
+    return input.includes('your-trigger');
+  },
+
+  async execute(input, context) {
+    // Implement skill logic
+    return {
+      success: true,
+      data: { /* results */ }
+    };
+  }
+};
+```
+
+## 📚 Documentation
+
+### Writing Guidelines
+
+- Use clear, concise language
+- Include code examples
+- Add diagrams where helpful
+- Keep documentation up-to-date
+
+### Documentation Structure
+
+```
+docs/
+├── getting-started.md
+├── configuration.md
+├── skills.md
+├── learning.md
+├── architecture.md
+└── api-reference.md
+```
+
+## 🧪 Testing Guidelines
+
+### Unit Tests
+
+```javascript
+describe('YourFeature', () => {
+  it('should do something', async () => {
+    const input = {};
+    const result = await yourFunction(input);
+    expect(result).toBeDefined();
+  });
+});
+```
+
+### Integration Tests
+
+```javascript
+describe('Skill Integration', () => {
+  it('should work with learning system', async () => {
+    // Test skill + learning integration
+  });
+});
+```
+
+## 🚀 Release Process
+
+1. Update version in package.json
+2. Update CHANGELOG.md
+3. Create release branch
+4. Run full test suite
+5. Create GitHub release
+6. Publish to npm
+
+## 📋 PR Checklist
+
+Before submitting:
+
+- [ ] Code follows style guidelines
+- [ ] Tests are written and passing
+- [ ] Documentation is updated
+- [ ] Commit messages are clear
+- [ ] No breaking changes (or documented)
+
+## 🏷️ Issue Labels
+
+- `bug`: Something isn't working
+- `enhancement`: New feature or request
+- `documentation`: Documentation improvements
+- `good first issue`: Good for newcomers
+- `help wanted`: Extra attention needed
+
+## 📞 Getting Help
+
+- **GitHub Discussions**: Questions and discussions
+- **GitHub Issues**: Bug reports and features
+- **Discord**: Community chat
+
+## 🎉 Recognition
+
+Contributors will be:
+- Listed in CONTRIBUTORS.md
+- Mentioned in release notes
+- Invited to maintainer team (significant contributions)
+
+## 📄 License
+
+By contributing, you agree your contributions will be licensed under MIT License.
+
+---
+
+Thank you for contributing to FlowMind! 🚀

package/README.md

@@ -4,34 +4,40 @@
 
 ### **The AI Agent That Learns How You Work**
 
-*An adaptive memory and workflow layer for MCP-based developer tools.*
+*Memory and workflow automation for MCP, Codex, and Claude Code.*
 
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](CONTRIBUTING.md)
-[![Version](https://img.shields.io/badge/version-1.4.5-blue)](CHANGELOG.md)
+[![npm version](https://img.shields.io/npm/v/flowmind.svg)](https://www.npmjs.com/package/flowmind)
+[![npm downloads](https://img.shields.io/npm/dw/flowmind.svg)](https://www.npmjs.com/package/flowmind)
 
-[中文](README_CN.md) | [Quick Start](#-quick-start) | [How It Works](#-how-it-works) | [Use Cases](#-use-cases) | [Architecture](#-architecture)
+[中文](README_CN.md) | [Quick Start](#-quick-start) | [Demo](demo/DEMO.md) | [Integration](docs/integration-guide.md) | [How It Works](#-how-it-works) | [Use Cases](#-use-cases) | [Architecture](#-architecture)
 
 </div>
 
 ---
 
-## One Core Value
+## Why Install It
 
-FlowMind helps you **teach a developer workflow once and reuse it later**.
+FlowMind helps you **teach a repeatable developer workflow once and reuse it later**.
 
-Today, the most reliable path in this repository is:
+It is built for engineers who already use `MCP`, `Codex`, `Claude Code`, or scriptable CLI workflows and want three things:
 
-1. Route a request to a skill
-2. Execute that skill through a configured adapter or MCP-compatible provider
-3. Capture explicit user feedback
-4. Re-apply that preference on the next similar run
+- A stable way to route tasks to reusable skills
+- A memory layer for explicit feedback and preferences
+- A CLI/MCP entrypoint instead of retyping the same instructions every time
 
-If you want one sentence:
+The shortest description is:
 
-> FlowMind is a memory layer for repetitive MCP-based developer operations.
+> FlowMind is a memory layer for repeatable developer operations.
 
-## A Runnable Example
+## 30-Second Demo
+
+For a longer walkthrough, see [demo/DEMO.md](demo/DEMO.md).
+
+Animated terminal walkthrough:
+
+![FlowMind terminal demo](https://raw.githubusercontent.com/Eleven-M/flowmind/master/demo/flowmind-demo.gif)
 
 ```bash
 # 1. Install
@@ -50,16 +56,16 @@ flowmind "下次用表格格式"
 flowmind-codex --skill log-audit "查询 traceId abc123 的日志"
 ```
 
-What you get today:
-- Skill routing
-- MCP/provider-aware execution contracts
+What you get immediately:
+- Reusable skill execution
 - Explicit feedback capture
-- Local persistence for preferences and learning
+- Local learning and preference reuse
+- Codex-friendly CLI access
 
-What this project is not yet:
-- A full autonomous coding agent
-- A complete SSH/remote code execution platform
-- A one-click deploy system for every workflow
+Best-fit use cases today:
+- Log and trace investigation
+- Review workflows with fixed standards
+- Internal tool orchestration through MCP-compatible adapters
 
 ## Quick Start
 
@@ -70,6 +76,21 @@ flowmind skills --json
 flowmind process --skill log-audit "查询 traceId abc123 的日志"
 ```
 
+If you want to try it without a global install:
+
+```bash
+npx flowmind@latest skills
+npx flowmind@latest doctor
+```
+
+If you want the fastest first success, start here:
+
+```bash
+flowmind doctor
+flowmind skills
+flowmind process --skill log-audit "query the latest error logs"
+```
+
 If you are integrating with Codex or scripts:
 
 ```bash
@@ -77,7 +98,22 @@ flowmind-codex skills
 flowmind-codex --skill log-audit "查询 traceId abc123 的日志"
 ```
 
-FlowMind stores learning data locally and uses that state to apply explicit feedback on future runs.
+FlowMind stores learning data locally and reuses explicit feedback on future runs.
+
+Need integration examples for Claude Code, Codex, Cursor, or MCP clients? See [docs/integration-guide.md](docs/integration-guide.md).
+
+## Who It Is For
+
+- Teams using MCP-based internal tools
+- Engineers repeatedly doing log analysis, review, validation, or doc sync work
+- Codex or Claude Code users who want repeatable workflows instead of prompt repetition
+
+## Why It Converts Better Than Raw Prompts
+
+- Skills define a stable execution path
+- Feedback becomes reusable state instead of chat history
+- CLI and MCP entrypoints make the workflow scriptable
+- Provider switching stays in config instead of in prompt text
 
 ---
 

package/README_CN.md

@@ -4,34 +4,40 @@
 
 ### **学习你工作方式的 AI 智能体**
 
-*一个面向 MCP 开发工作流的可学习记忆层。*
+*面向 MCP、Codex、Claude Code 的记忆层与工作流自动化工具。*
 
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](CONTRIBUTING.md)
-[![Version](https://img.shields.io/badge/version-1.4.5-blue)](CHANGELOG.md)
+[![npm version](https://img.shields.io/npm/v/flowmind.svg)](https://www.npmjs.com/package/flowmind)
+[![npm downloads](https://img.shields.io/npm/dw/flowmind.svg)](https://www.npmjs.com/package/flowmind)
 
-[English](README.md) | [快速开始](#-快速开始) | [工作原理](#-工作原理) | [使用场景](#-使用场景) | [架构](#-架构)
+[English](README.md) | [快速开始](#-快速开始) | [演示](demo/DEMO_CN.md) | [集成指南](docs/integration-guide.md) | [工作原理](#-工作原理) | [使用场景](#-使用场景) | [架构](#-架构)
 
 </div>
 
 ---
 
-## 一个核心价值
+## 为什么值得安装
 
 FlowMind 的目标不是“什么都做”，而是把**重复出现的开发工作流记住并复用**。
 
-当前仓库里最可靠、最能跑通的一条主链路是：
+它更适合已经在使用 `MCP`、`Codex`、`Claude Code` 或脚本化 CLI 的开发者，核心价值有三点：
 
-1. 把请求路由到合适的 skill
-2. 通过已配置的 adapter / MCP 兼容提供者执行 skill
-3. 捕获用户的显式反馈
-4. 在下次相似请求里复用这份偏好
+- 用 skill 路由可复用任务
+- 用显式反馈沉淀偏好和执行习惯
+- 用 CLI / MCP 入口替代重复输 prompt
 
 一句话概括：
 
-> FlowMind 是一个给 MCP 开发工具使用的记忆层。
+> FlowMind 是一个面向重复开发操作的记忆层。
 
-## 一个可跑通的例子
+## 30 秒跑通示例
+
+更完整的演示见 [demo/DEMO_CN.md](demo/DEMO_CN.md)。
+
+终端操作 GIF 演示：
+
+![FlowMind 终端演示](https://raw.githubusercontent.com/Eleven-M/flowmind/master/demo/flowmind-demo.gif)
 
 ```bash
 # 1. 安装
@@ -50,16 +56,16 @@ flowmind "下次用表格格式"
 flowmind-codex --skill log-audit "查询 traceId abc123 的日志"
 ```
 
-现在已经具备的能力：
-- skill 路由
-- 面向 MCP/provider 的执行协议
+你现在就能拿到的价值：
+- 可复用的 skill 执行入口
 - 显式反馈学习
-- 本地持久化学习记录和偏好
+- 本地持久化偏好
+- 对 Codex 更友好的 CLI 接口
 
-当前还不应该过度承诺的部分：
-- 不是完整的自治编码 Agent
-- 不是通用 SSH 远程执行平台
-- 不是所有工作流都已实现一键自动化
+当前最适合的场景：
+- 日志与 trace 排查
+- 有固定标准的代码审查
+- 通过 MCP 适配器串联内部工具
 
 ## 快速开始
 
@@ -70,6 +76,21 @@ flowmind skills --json
 flowmind process --skill log-audit "查询 traceId abc123 的日志"
 ```
 
+如果你想先试一下，不想全局安装：
+
+```bash
+npx flowmind@latest skills
+npx flowmind@latest doctor
+```
+
+如果你想最快验证它是否适合你，先跑这组命令：
+
+```bash
+flowmind doctor
+flowmind skills
+flowmind process --skill log-audit "查询最近的错误日志"
+```
+
 如果你要集成到 Codex 或脚本：
 
 ```bash
@@ -79,6 +100,21 @@ flowmind-codex --skill log-audit "查询 traceId abc123 的日志"
 
 FlowMind 会把学习数据保存在本地，并在后续运行中应用这些显式反馈。
 
+如果你要接入 Claude Code、Codex、Cursor 或 MCP 客户端，可以直接看 [docs/integration-guide.md](docs/integration-guide.md)。
+
+## 适合谁
+
+- 已经接入 MCP 内部工具的团队
+- 经常重复做日志排查、代码审查、数据校验、文档同步的工程师
+- 希望把工作流沉淀给 Codex 或 Claude Code 复用的人
+
+## 为什么比直接写 Prompt 更稳
+
+- skill 提供稳定的执行路径
+- 反馈会沉淀成状态，而不是停留在聊天记录里
+- CLI 和 MCP 入口更容易脚本化
+- 切换 provider 主要靠配置，不靠重新组织 prompt
+
 ---
 
 ## 📖 使用方式

package/demo/01-skills.sh

@@ -0,0 +1,9 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+source "$(cd "$(dirname "$0")" && pwd)/common.sh"
+FLOWMIND_LABEL="$(flowmind_label)"
+
+printf '$ %s skills --json | jq '\''.skills[:4] | map({name, category, version})'\''\n' "$FLOWMIND_LABEL"
+run_flowmind skills --json | jq '.skills[:4] | map({name, category, version})'

package/demo/02-log-audit.sh

@@ -0,0 +1,9 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+source "$(cd "$(dirname "$0")" && pwd)/common.sh"
+FLOWMIND_LABEL="$(flowmind_label)"
+
+printf '$ %s process --skill log-audit "查询 traceId demo-123 的日志"\n' "$FLOWMIND_LABEL"
+run_flowmind process --skill log-audit "查询 traceId demo-123 的日志"

package/demo/03-learn-format.sh

@@ -0,0 +1,9 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+source "$(cd "$(dirname "$0")" && pwd)/common.sh"
+FLOWMIND_LABEL="$(flowmind_label)"
+
+printf '$ %s process "下次日志结果用表格格式"\n' "$FLOWMIND_LABEL"
+run_flowmind process "下次日志结果用表格格式"

package/demo/04-show-learning.sh

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+source "$(cd "$(dirname "$0")" && pwd)/common.sh"
+
+printf '$ cat $FLOWMIND_HOME/.flowmind/learning/records/global/preferences.json\n'
+cat "$FLOWMIND_HOME/.flowmind/learning/records/global/preferences.json"

package/demo/05-log-audit-json.sh

@@ -0,0 +1,9 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+source "$(cd "$(dirname "$0")" && pwd)/common.sh"
+FLOWMIND_LABEL="$(flowmind_label)"
+
+printf '$ %s process --skill log-audit "查询 traceId demo-456 的日志" --json | jq '\''{skill: .metadata.skill, traceId: .data.data.params.traceId, message: .data.message}'\''\n' "$FLOWMIND_LABEL"
+run_flowmind process --skill log-audit "查询 traceId demo-456 的日志" --json | jq '{skill: .metadata.skill, traceId: .data.data.params.traceId, message: .data.message}'