@our2ndbrain/cli 2026.4.4 → 2026.4.5

package/README_en.md

@@ -0,0 +1,108 @@
+# 🧠 2ndBrain
+
+> A lightweight entrypoint for AI agents and human collaborators: use the 2ndBrain template, CLI, and Skill to operate an Obsidian knowledge base together.
+
+[English](README_en.md) | [简体中文](README.md)
+
+[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
+[![npm version](https://img.shields.io/npm/v/@our2ndbrain/cli.svg)](https://www.npmjs.com/package/@our2ndbrain/cli)
+
+## What This Repository Is
+
+If you hand this repository to an AI agent, this README should be the first file it reads.
+
+2ndBrain ships three things:
+
+- an Obsidian vault template with PARA folders, inboxes, and dashboards
+- a CLI for checking the environment, initializing a vault, and updating framework files
+- a 2ndBrain Skill that teaches the agent how to capture, organize, review, and process content
+
+This README keeps only the minimum needed for AI collaboration. For the fuller project and methodology reference, see the [detailed guide](https://github.com/Our2ndBrain/2ndBrain-Template/blob/main/docs/guide_en.md).
+
+## Quick Start
+
+The default path is `npx`:
+
+```bash
+npx @our2ndbrain/cli@latest check
+npx @our2ndbrain/cli@latest init my-brain
+cd my-brain
+npx @our2ndbrain/cli@latest member Alice
+```
+
+If the CLI is already installed globally, you can also use:
+
+```bash
+2ndbrain check
+2ndbrain init my-brain
+cd my-brain
+2ndbrain member Alice
+```
+
+## Initialize a Vault
+
+### Create a new 2ndBrain vault
+
+```bash
+npx @our2ndbrain/cli@latest check
+npx @our2ndbrain/cli@latest init my-brain
+cd my-brain
+npx @our2ndbrain/cli@latest member Alice
+```
+
+### Integrate into an existing Obsidian vault
+
+```bash
+cd my-existing-vault
+npx @our2ndbrain/cli@latest check
+npx @our2ndbrain/cli@latest init
+npx @our2ndbrain/cli@latest member Alice
+```
+
+After initialization, guide the user to:
+
+1. open the directory in Obsidian
+2. click "Trust author and enable plugins"
+3. create the first daily note and start capturing tasks and thoughts
+
+## Install the Skill
+
+The preferred installation path is the SSH git URL form:
+
+```bash
+npx skills add git@github.com:Our2ndBrain/2ndBrain-Template.git --skill 2ndbrain
+```
+
+To target a specific agent explicitly:
+
+```bash
+npx skills add git@github.com:Our2ndBrain/2ndBrain-Template.git --skill 2ndbrain -a claude-code
+npx skills add git@github.com:Our2ndBrain/2ndBrain-Template.git --skill 2ndbrain -a cursor
+npx skills add git@github.com:Our2ndBrain/2ndBrain-Template.git --skill 2ndbrain -a openclaw
+```
+
+If you are not using the `skills` CLI in that environment yet, you can still fall back to manually copying `skills/2ndbrain/`.
+
+The skill entrypoint is [SKILL.md](https://github.com/Our2ndBrain/2ndBrain-Template/blob/main/skills/2ndbrain/SKILL.md).
+
+## How AI Should Collaborate With Humans
+
+An AI agent using this template should at least follow these rules:
+
+- Run `2ndbrain check` or `npx @our2ndbrain/cli@latest check` before setup, initialization, or takeover.
+- Capture before organizing. If placement is unclear, write it to `10_Inbox/{member}/` first.
+- Write tasks to `10_Inbox/{member}/00_To-Do.md`. Do not hand-edit query-driven files such as `00_Dashboard/*.md` or `10_Inbox/*/01_Tasks.md`.
+- Follow the user's language instead of switching languages on your own.
+- Prefer the 2ndBrain Skill for capture, organize, review, content processing, and scheduled cleanup.
+- When you need detailed rules, read the Skill and its references instead of inferring policy from this README.
+
+## Deep Reading
+
+- [Detailed Guide (English)](https://github.com/Our2ndBrain/2ndBrain-Template/blob/main/docs/guide_en.md)
+- [详细指南（中文）](https://github.com/Our2ndBrain/2ndBrain-Template/blob/main/docs/guide.md)
+- [2ndBrain Skill](https://github.com/Our2ndBrain/2ndBrain-Template/blob/main/skills/2ndbrain/SKILL.md)
+- [Setup Reference](https://github.com/Our2ndBrain/2ndBrain-Template/blob/main/skills/2ndbrain/references/setup.md)
+- [Operations and Daily Review](https://github.com/Our2ndBrain/2ndBrain-Template/blob/main/skills/2ndbrain/references/operations.md)
+- [Content Processing](https://github.com/Our2ndBrain/2ndBrain-Template/blob/main/skills/2ndbrain/references/content-processing.md)
+- [Scheduling and Automation](https://github.com/Our2ndBrain/2ndBrain-Template/blob/main/skills/2ndbrain/references/scheduling.md)
+- [Task Conventions](https://github.com/Our2ndBrain/2ndBrain-Template/blob/main/skills/2ndbrain/references/task-conventions.md)

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@our2ndbrain/cli",
-    "version": "2026.4.4",
+    "version": "2026.4.5",
     "description": "CLI tool for 2ndBrain - A personal knowledge management system based on PARA + C-O-R-D + Append-and-Review",
     "keywords": [
         "2ndbrain",
@@ -24,15 +24,13 @@
     "files": [
         "bin/",
         "src/",
-        ".obsidian/",
-        "00_Dashboard/",
-        "10_Inbox/Agents/",
-        "99_System/",
+        "template/",
         "AGENTS.md",
         "CHANGELOG.md",
         "CLAUDE.md",
         "LICENSE",
-        "README.md"
+        "README.md",
+        "README_en.md"
     ],
     "bugs": {
         "url": "https://github.com/Our2ndBrain/2ndBrain-Template/issues"

package/src/commands/init.js

@@ -7,6 +7,7 @@
 const path = require('path');
 const fs = require('fs-extra');
 const {
+  PACKAGE_ROOT,
   TEMPLATE_ROOT,
   FRAMEWORK_FILES,
   FRAMEWORK_DIRS,
@@ -14,6 +15,7 @@ const {
   COPY_DIRS,
   SMART_COPY_DIRS,
   INIT_ONLY_FILES,
+  getFrameworkSourcePath,
   is2ndBrainProject,
 } = require('../lib/config');
 const { copyFiles, ensureDirs, createFile, isDirEmpty, copyFilesSmart } = require('../lib/files');
@@ -141,6 +143,7 @@ async function handleObsidianReset(obsidianSrc, obsidianDest, log, skipConfirmat
 async function init(targetPath, options, log) {
   const resolvedPath = path.resolve(targetPath);
   const templateRoot = options.template ? path.resolve(options.template) : TEMPLATE_ROOT;
+  const packageRoot = options.template ? path.resolve(templateRoot, '..') : PACKAGE_ROOT;
 
   log.info(`Initializing 2ndBrain project at: ${resolvedPath}`);
   log.info(`Using template from: ${templateRoot}`);
@@ -217,7 +220,7 @@ async function init(targetPath, options, log) {
   log.info('Copying framework files...');
   const fileResult = await copyFilesSmart(
     FRAMEWORK_FILES,
-    templateRoot,
+    (file) => getFrameworkSourcePath(file, { templateRoot, packageRoot }),
     resolvedPath,
     {},
     (file, action, detail) => {

package/src/commands/update.js

@@ -8,9 +8,11 @@ const path = require('path');
 const fs = require('fs-extra');
 const chalk = require('chalk');
 const {
+  PACKAGE_ROOT,
   TEMPLATE_ROOT,
   FRAMEWORK_FILES,
   SMART_COPY_DIRS,
+  getFrameworkSourcePath,
   is2ndBrainProject,
 } = require('../lib/config');
 const {
@@ -35,6 +37,7 @@ const { copyObsidianDirSmart, MERGE_STRATEGIES } = require('../lib/obsidian');
 async function update(targetPath, options, log) {
   const resolvedPath = path.resolve(targetPath);
   const templateRoot = options.template ? path.resolve(options.template) : TEMPLATE_ROOT;
+  const packageRoot = options.template ? path.resolve(templateRoot, '..') : PACKAGE_ROOT;
 
   log.info(`Updating 2ndBrain project at: ${resolvedPath}`);
   log.info(`Using template from: ${templateRoot}`);
@@ -47,21 +50,22 @@ async function update(targetPath, options, log) {
   }
 
   if (options.dryRun) {
-    await performDryRun(resolvedPath, templateRoot, log);
+    await performDryRun(resolvedPath, templateRoot, packageRoot, log);
     return;
   }
 
   // Main update flow
-  await performUpdate(resolvedPath, templateRoot, options, log);
+  await performUpdate(resolvedPath, templateRoot, packageRoot, options, log);
 }
 
 /**
  * Perform dry run - show what would be updated
  * @param {string} resolvedPath - Target project path
  * @param {string} templateRoot - Template root path
+ * @param {string} packageRoot - Package root path
  * @param {Function} log - Logger function
  */
-async function performDryRun(resolvedPath, templateRoot, log) {
+async function performDryRun(resolvedPath, templateRoot, packageRoot, log) {
   log.warn('[DRY RUN] No files will be modified.');
   log.info('');
 
@@ -69,7 +73,7 @@ async function performDryRun(resolvedPath, templateRoot, log) {
 
   const result = await copyFilesSmart(
     FRAMEWORK_FILES,
-    templateRoot,
+    (file) => getFrameworkSourcePath(file, { templateRoot, packageRoot }),
     resolvedPath,
     { dryRun: true },
     (file, action, detail) => {
@@ -163,17 +167,18 @@ async function performDryRun(resolvedPath, templateRoot, log) {
  * Perform the actual update with user confirmation
  * @param {string} resolvedPath - Target project path
  * @param {string} templateRoot - Template root path
+ * @param {string} packageRoot - Package root path
  * @param {Object} options - Command options
  * @param {boolean} [options.yes] - Auto-confirm all updates
  * @param {Function} log - Logger function
  */
-async function performUpdate(resolvedPath, templateRoot, options, log) {
+async function performUpdate(resolvedPath, templateRoot, packageRoot, options, log) {
   log.info('Analyzing framework files...');
 
   // First pass: analyze all files
   const analysis = await copyFilesSmart(
     FRAMEWORK_FILES,
-    templateRoot,
+    (file) => getFrameworkSourcePath(file, { templateRoot, packageRoot }),
     resolvedPath,
     {},
     (file, action, detail) => {
@@ -218,7 +223,7 @@ async function performUpdate(resolvedPath, templateRoot, options, log) {
   if (userChoice === 'all') {
     // Apply all changes
     for (const change of changes) {
-      const src = path.join(templateRoot, change.file);
+      const src = getFrameworkSourcePath(change.file, { templateRoot, packageRoot });
       const resolvedSrc = await resolveTemplateSourcePath(src, change.file);
       const dest = path.join(resolvedPath, change.file);
 
@@ -245,7 +250,7 @@ async function performUpdate(resolvedPath, templateRoot, options, log) {
     // Review each file individually
     for (const change of changes) {
       const file = change.file;
-      const src = path.join(templateRoot, file);
+      const src = getFrameworkSourcePath(file, { templateRoot, packageRoot });
       const resolvedSrc = await resolveTemplateSourcePath(src, file);
       const dest = path.join(resolvedPath, file);
 

package/src/lib/config.js

@@ -6,8 +6,20 @@
 
 const path = require('path');
 
-// Template root directory (npm package root)
-const TEMPLATE_ROOT = path.resolve(__dirname, '../../');
+// npm package root containing CLI docs and metadata
+const PACKAGE_ROOT = path.resolve(__dirname, '../..');
+
+// Vault template root containing shipped vault assets
+const TEMPLATE_ROOT = path.join(PACKAGE_ROOT, 'template');
+
+const PACKAGE_DOC_FILES = [
+  'AGENTS.md',
+  'README.md',
+  'README_en.md',
+  'CHANGELOG.md',
+  'CLAUDE.md',
+  'LICENSE',
+];
 
 /**
  * Framework files - managed by init/update/remove commands
@@ -16,6 +28,7 @@ const TEMPLATE_ROOT = path.resolve(__dirname, '../../');
 const FRAMEWORK_FILES = [
   'AGENTS.md',
   'README.md',
+  'README_en.md',
   'CHANGELOG.md',
   'CLAUDE.md',
   'LICENSE',
@@ -84,6 +97,32 @@ function getTemplatePath(relativePath, templateRoot = TEMPLATE_ROOT) {
   return path.join(templateRoot, relativePath);
 }
 
+/**
+ * Check whether a framework file is sourced from the package root docs.
+ * @param {string} relativePath - Relative framework file path
+ * @returns {boolean}
+ */
+function isPackageDocFile(relativePath) {
+  return PACKAGE_DOC_FILES.includes(relativePath);
+}
+
+/**
+ * Resolve the source path for a framework file.
+ * Package docs come from the npm package root; vault assets come from template/.
+ * @param {string} relativePath - Relative framework file path
+ * @param {Object} [options]
+ * @param {string} [options.templateRoot] - Template directory override
+ * @param {string} [options.packageRoot] - Package root override
+ * @returns {string} Absolute source path
+ */
+function getFrameworkSourcePath(
+  relativePath,
+  { templateRoot = TEMPLATE_ROOT, packageRoot = PACKAGE_ROOT } = {}
+) {
+  const sourceRoot = isPackageDocFile(relativePath) ? packageRoot : templateRoot;
+  return path.join(sourceRoot, relativePath);
+}
+
 /**
  * Check if a path is a 2ndBrain project
  * @param {string} targetPath - Path to check
@@ -100,7 +139,9 @@ function is2ndBrainProject(targetPath) {
 }
 
 module.exports = {
+  PACKAGE_ROOT,
   TEMPLATE_ROOT,
+  PACKAGE_DOC_FILES,
   FRAMEWORK_FILES,
   FRAMEWORK_DIRS,
   USER_DATA_DIRS,
@@ -109,5 +150,7 @@ module.exports = {
   INIT_ONLY_FILES,
   MARKER_FILE,
   getTemplatePath,
+  isPackageDocFile,
+  getFrameworkSourcePath,
   is2ndBrainProject,
 };

package/src/lib/files.js

@@ -45,16 +45,19 @@ async function copyFile(src, dest) {
 /**
  * Copy multiple files from template to target
  * @param {string[]} files - Array of relative file paths
- * @param {string} templateRoot - Template root directory
+ * @param {string|Function} sourceRootOrResolver - Source root directory or resolver
  * @param {string} targetRoot - Target root directory
  * @param {Function} [onFile] - Callback for each file (relativePath, action)
  * @returns {Promise<{copied: string[], skipped: string[], errors: string[]}>}
  */
-async function copyFiles(files, templateRoot, targetRoot, onFile) {
+async function copyFiles(files, sourceRootOrResolver, targetRoot, onFile) {
   const result = { copied: [], skipped: [], errors: [] };
 
   for (const file of files) {
-    const src = await resolveSourcePath(path.join(templateRoot, file));
+    const requestedSrc = typeof sourceRootOrResolver === 'function'
+      ? sourceRootOrResolver(file)
+      : path.join(sourceRootOrResolver, file);
+    const src = await resolveSourcePath(requestedSrc);
     const dest = path.join(targetRoot, file);
 
     try {
@@ -302,7 +305,7 @@ async function copyFileWithCompare(src, dest, options = {}) {
 /**
  * Copy multiple files with smart comparison
  * @param {string[]} files - Array of relative file paths
- * @param {string} templateRoot - Template root directory
+ * @param {string|Function} sourceRootOrResolver - Source root directory or resolver
  * @param {string} targetRoot - Target root directory
  * @param {Object} options - Copy options
  * @param {boolean} [options.force] - Force copy even if equal
@@ -310,7 +313,7 @@ async function copyFileWithCompare(src, dest, options = {}) {
  * @param {Function} [onFile] - Callback for each file (relativePath, action, detail)
  * @returns {Promise<{copied: string[], skipped: string[], unchanged: string[], errors: string[], changes: Array}>}
  */
-async function copyFilesSmart(files, templateRoot, targetRoot, options = {}, onFile) {
+async function copyFilesSmart(files, sourceRootOrResolver, targetRoot, options = {}, onFile) {
   const result = {
     copied: [],
     skipped: [],
@@ -320,7 +323,9 @@ async function copyFilesSmart(files, templateRoot, targetRoot, options = {}, onF
   };
 
   for (const file of files) {
-    const src = path.join(templateRoot, file);
+    const src = typeof sourceRootOrResolver === 'function'
+      ? sourceRootOrResolver(file)
+      : path.join(sourceRootOrResolver, file);
     const dest = path.join(targetRoot, file);
 
     try {