@clawrise/clawrise-cli 0.1.0-alpha.5 → 0.1.0-alpha.6

package/README.md

@@ -1,11 +1,17 @@
 # @clawrise/clawrise-cli
 
-通过 npm 分发的 Clawrise CLI 根包。
+Clawrise CLI root package distributed through npm.
 
-用户安装方式：
+## Install Globally
 
 ```bash
 npm install -g @clawrise/clawrise-cli
 ```
 
-安装后会自动选择当前平台对应的预编译二进制，并携带第一方 `feishu` / `notion` provider plugin。
+## For AI
+
+Send the following prompt to the AI assistant:
+
+```text
+Access https://raw.githubusercontent.com/repothread/clawrise-cli/main/docs/en/ai-install.md and follow the steps there to install the `clawrise` command and run setup for the current client.
+```

package/bin/clawrise.js

@@ -5,6 +5,21 @@
 const childProcess = require('child_process');
 const path = require('path');
 const { resolvePlatformPackage } = require('../lib/platform');
+const { handleSetupCommand } = require('../lib/setup');
+
+const rawArgs = process.argv.slice(2);
+
+if (rawArgs[0] === 'setup') {
+  try {
+    const handledExitCode = handleSetupCommand(rawArgs.slice(1));
+    if (typeof handledExitCode === 'number') {
+      process.exit(handledExitCode);
+    }
+  } catch (error) {
+    console.error(error.message);
+    process.exit(1);
+  }
+}
 
 const platformPackage = resolvePlatformPackage();
 const pluginPath = path.join(platformPackage.dir, 'plugins');
@@ -14,7 +29,7 @@ nextEnv.CLAWRISE_PLUGIN_PATHS = nextEnv.CLAWRISE_PLUGIN_PATHS
   ? `${pluginPath}${path.delimiter}${nextEnv.CLAWRISE_PLUGIN_PATHS}`
   : pluginPath;
 
-const result = childProcess.spawnSync(platformPackage.binaryPath, process.argv.slice(2), {
+const result = childProcess.spawnSync(platformPackage.binaryPath, rawArgs, {
   stdio: 'inherit',
   env: nextEnv,
 });

package/lib/platform.js

@@ -1,29 +1,34 @@
 'use strict';
 
+const fs = require('fs');
 const path = require('path');
 
-const packageMap = {
-  'darwin:arm64': 'clawrise-cli-darwin-arm64',
-  'darwin:x64': 'clawrise-cli-darwin-x64',
-  'linux:arm64': 'clawrise-cli-linux-arm64',
-  'linux:x64': 'clawrise-cli-linux-x64',
-  'win32:arm64': 'clawrise-cli-win32-arm64',
-  'win32:x64': 'clawrise-cli-win32-x64',
+const platformSuffixMap = {
+  'darwin:arm64': 'darwin-arm64',
+  'darwin:x64': 'darwin-x64',
+  'linux:arm64': 'linux-arm64',
+  'linux:x64': 'linux-x64',
+  'win32:arm64': 'win32-arm64',
+  'win32:x64': 'win32-x64',
 };
 
 function resolvePlatformPackage() {
   const platformKey = `${process.platform}:${process.arch}`;
-  const packageName = packageMap[platformKey];
+  const packageSuffix = platformSuffixMap[platformKey];
 
-  if (!packageName) {
-    throw new Error(`当前平台暂不支持: ${process.platform}/${process.arch}`);
+  if (!packageSuffix) {
+    throw new Error(`The current platform is not supported: ${process.platform}/${process.arch}`);
   }
 
+  // Keep the platform package under the same scope / prefix as the root package,
+  // otherwise scoped releases cannot resolve the installed platform bundle.
+  const packageName = appendPackageSuffix(resolveRootPackageName(), packageSuffix);
+
   let packageJSONPath;
   try {
     packageJSONPath = require.resolve(`${packageName}/package.json`);
   } catch (error) {
-    throw new Error(`未找到当前平台对应的二进制包 ${packageName}，请重新执行 npm install clawrise-cli。`);
+    throw new Error(`The platform binary package ${packageName} was not found. Re-run npm install for the root package.`);
   }
 
   const packageDir = path.dirname(packageJSONPath);
@@ -36,6 +41,41 @@ function resolvePlatformPackage() {
   };
 }
 
+function resolveRootPackageName() {
+  const envName = String(process.env.CLAWRISE_ROOT_PACKAGE_NAME || '').trim();
+  if (envName !== '') {
+    return envName;
+  }
+
+  const packageJSONPath = path.join(resolvePackageRootDir(), 'package.json');
+  if (!fs.existsSync(packageJSONPath)) {
+    throw new Error(`The root package metadata was not found: ${packageJSONPath}`);
+  }
+
+  const packageJSON = JSON.parse(fs.readFileSync(packageJSONPath, 'utf8'));
+  const packageName = String(packageJSON.name || '').trim();
+  if (packageName === '') {
+    throw new Error(`The root package name is missing in ${packageJSONPath}`);
+  }
+  return packageName;
+}
+
+function resolvePackageRootDir() {
+  return path.resolve(__dirname, '..');
+}
+
+function appendPackageSuffix(packageName, suffix) {
+  if (packageName.startsWith('@')) {
+    const separatorIndex = packageName.indexOf('/');
+    if (separatorIndex > 0 && separatorIndex < packageName.length - 1) {
+      const scope = packageName.slice(0, separatorIndex + 1);
+      const baseName = packageName.slice(separatorIndex + 1);
+      return `${scope}${baseName}-${suffix}`;
+    }
+  }
+  return `${packageName}-${suffix}`;
+}
+
 module.exports = {
   resolvePlatformPackage,
 };

package/lib/setup.js

@@ -0,0 +1,376 @@
+'use strict';
+
+const childProcess = require('child_process');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const supportedClients = ['codex', 'claude-code', 'openclaw', 'opencode'];
+const supportedPlatforms = ['feishu', 'notion'];
+const platformSkillMap = {
+  feishu: 'clawrise-feishu',
+  notion: 'clawrise-notion',
+};
+
+function handleSetupCommand(rawArgs) {
+  const parsed = parseSetupArgs(rawArgs);
+  ensureValidClient(parsed.client);
+  ensureValidPlatforms(parsed.platforms);
+  ensureCLICommandInstalled(parsed);
+
+  const targetRootDir = resolveClientSkillsDir(parsed);
+  const selectedSkills = resolveRequestedSkillNames(parsed.platforms);
+  const targetName = displayClientName(parsed.client);
+
+  installBundledSkillsInto(selectedSkills, targetRootDir, targetName);
+  return 0;
+}
+
+function parseSetupArgs(args) {
+  const result = {
+    client: '',
+    platforms: [],
+    codexHome: '',
+    claudeHome: '',
+    openclawHome: '',
+    opencodeConfigHome: '',
+    skillsDir: '',
+    skipCliInstall: false,
+  };
+
+  for (let index = 0; index < args.length; index += 1) {
+    const token = String(args[index] || '').trim();
+    if (token === '') {
+      continue;
+    }
+
+    if (token === '--codex-home') {
+      result.codexHome = readFlagValue(args, index, '--codex-home');
+      index += 1;
+      continue;
+    }
+
+    if (token === '--claude-home') {
+      result.claudeHome = readFlagValue(args, index, '--claude-home');
+      index += 1;
+      continue;
+    }
+
+    if (token === '--openclaw-home') {
+      result.openclawHome = readFlagValue(args, index, '--openclaw-home');
+      index += 1;
+      continue;
+    }
+
+    if (token === '--opencode-config-home') {
+      result.opencodeConfigHome = readFlagValue(args, index, '--opencode-config-home');
+      index += 1;
+      continue;
+    }
+
+    if (token === '--skills-dir') {
+      result.skillsDir = readFlagValue(args, index, '--skills-dir');
+      index += 1;
+      continue;
+    }
+
+    if (token === '--skip-cli-install') {
+      result.skipCliInstall = true;
+      continue;
+    }
+
+    if (token === '--help' || token === '-h' || token === 'help') {
+      printSetupHelp();
+      process.exit(0);
+    }
+
+    if (token.startsWith('-')) {
+      throw new Error(`Unsupported argument: ${token}`);
+    }
+
+    if (result.client === '') {
+      result.client = token;
+      continue;
+    }
+
+    result.platforms.push(token);
+  }
+
+  if (result.client === '') {
+    printSetupHelp();
+    process.exit(0);
+  }
+
+  return result;
+}
+
+function readFlagValue(args, index, flagName) {
+  const value = String(args[index + 1] || '').trim();
+  if (value === '') {
+    throw new Error(`${flagName} requires a directory argument.`);
+  }
+  return value;
+}
+
+function ensureValidClient(client) {
+  if (supportedClients.includes(client)) {
+    return;
+  }
+  throw new Error(`Unsupported client: ${client}. Supported clients: ${supportedClients.join(', ')}`);
+}
+
+function ensureValidPlatforms(platforms) {
+  const invalidPlatforms = platforms.filter((platform) => !supportedPlatforms.includes(platform));
+  if (invalidPlatforms.length === 0) {
+    return;
+  }
+  throw new Error(`Unsupported platform: ${invalidPlatforms.join(', ')}. Supported platforms: ${supportedPlatforms.join(', ')}`);
+}
+
+function ensureCLICommandInstalled(parsed) {
+  if (parsed.skipCliInstall) {
+    console.log('Skipping global CLI installation because --skip-cli-install was set.');
+    return;
+  }
+
+  if (!shouldInstallCLI()) {
+    console.log('The clawrise command is already available. Skipping global CLI installation.');
+    return;
+  }
+
+  if (!isCommandAvailable('npm')) {
+    throw new Error('npm is required to install the clawrise command globally.');
+  }
+
+  const packageName = resolveCurrentPackageName();
+  console.log(`Installing the clawrise command globally from npm package: ${packageName}`);
+
+  const result = childProcess.spawnSync('npm', ['install', '-g', packageName], {
+    stdio: 'inherit',
+  });
+
+  if (result.error) {
+    throw result.error;
+  }
+  if (typeof result.status === 'number' && result.status !== 0) {
+    throw new Error(`Global CLI installation failed with exit code ${result.status}.`);
+  }
+}
+
+function shouldInstallCLI() {
+  if (isProbablyNPXInvocation()) {
+    return true;
+  }
+  return !isCommandAvailable('clawrise');
+}
+
+function isProbablyNPXInvocation() {
+  const executablePath = resolveCurrentExecutablePath();
+  return executablePath.includes(`${path.sep}_npx${path.sep}`);
+}
+
+function resolveCurrentExecutablePath() {
+  const currentPath = process.argv[1] || __filename;
+  try {
+    return fs.realpathSync(currentPath);
+  } catch (error) {
+    return path.resolve(currentPath);
+  }
+}
+
+function isCommandAvailable(commandName) {
+  const resolverCommand = process.platform === 'win32' ? 'where' : 'which';
+  const result = childProcess.spawnSync(resolverCommand, [commandName], {
+    stdio: 'ignore',
+  });
+  return typeof result.status === 'number' && result.status === 0;
+}
+
+function resolveCurrentPackageName() {
+  const envName = String(process.env.CLAWRISE_ROOT_PACKAGE_NAME || '').trim();
+  if (envName !== '') {
+    return envName;
+  }
+
+  const packageJSONPath = path.join(resolvePackageRootDir(), 'package.json');
+  if (fs.existsSync(packageJSONPath)) {
+    const packageJSON = JSON.parse(fs.readFileSync(packageJSONPath, 'utf8'));
+    if (typeof packageJSON.name === 'string' && packageJSON.name.trim() !== '') {
+      return packageJSON.name.trim();
+    }
+  }
+
+  return '@clawrise/clawrise-cli';
+}
+
+function resolvePackageRootDir() {
+  return path.resolve(__dirname, '..');
+}
+
+function resolveRequestedSkillNames(platforms) {
+  const orderedSkills = ['clawrise-core'];
+  for (const platform of platforms) {
+    const skillName = platformSkillMap[platform];
+    if (skillName && !orderedSkills.includes(skillName)) {
+      orderedSkills.push(skillName);
+    }
+  }
+  return orderedSkills;
+}
+
+function installBundledSkillsInto(selectedSkills, targetRootDir, targetName) {
+  const skillsDir = resolveBundledSkillsDir();
+  const packagedSkills = listSkillDirectories(skillsDir);
+
+  if (packagedSkills.length === 0) {
+    throw new Error('No bundled skills were found in the current npm package.');
+  }
+
+  const invalidSkills = selectedSkills.filter((name) => !packagedSkills.includes(name));
+  if (invalidSkills.length > 0) {
+    throw new Error(`The following skills are not bundled in the current npm package: ${invalidSkills.join(', ')}`);
+  }
+
+  fs.mkdirSync(targetRootDir, { recursive: true });
+
+  for (const skillName of selectedSkills) {
+    const sourceDir = path.join(skillsDir, skillName);
+    const targetDir = path.join(targetRootDir, skillName);
+    fs.rmSync(targetDir, { recursive: true, force: true });
+    copyTree(sourceDir, targetDir);
+    console.log(`Installed skill: ${skillName} -> ${targetDir}`);
+  }
+
+  console.log(`Setup completed for ${targetName}. Start a new session or restart the client to load the new skills.`);
+}
+
+function resolveBundledSkillsDir() {
+  return path.join(resolvePackageRootDir(), 'skills');
+}
+
+function resolveClientSkillsDir(parsed) {
+  if (String(parsed.skillsDir || '').trim() !== '') {
+    return path.resolve(parsed.skillsDir);
+  }
+
+  switch (parsed.client) {
+    case 'codex':
+      return path.join(resolveCodexHome(parsed.codexHome), 'skills');
+    case 'claude-code':
+      return path.join(resolveClaudeCodeHome(parsed.claudeHome), 'skills');
+    case 'openclaw':
+      return path.join(resolveOpenClawHome(parsed.openclawHome), 'skills');
+    case 'opencode':
+      return path.join(resolveOpenCodeConfigHome(parsed.opencodeConfigHome), 'skills');
+    default:
+      throw new Error(`Unsupported client: ${parsed.client}`);
+  }
+}
+
+function displayClientName(client) {
+  switch (client) {
+    case 'codex':
+      return 'Codex';
+    case 'claude-code':
+      return 'Claude Code';
+    case 'openclaw':
+      return 'OpenClaw';
+    case 'opencode':
+      return 'OpenCode';
+    default:
+      return client;
+  }
+}
+
+function resolveCodexHome(explicitValue) {
+  const value = String(explicitValue || process.env.CODEX_HOME || '').trim();
+  if (value !== '') {
+    return path.resolve(value);
+  }
+  return path.join(os.homedir(), '.codex');
+}
+
+function resolveClaudeCodeHome(explicitValue) {
+  const value = String(explicitValue || process.env.CLAUDE_HOME || '').trim();
+  if (value !== '') {
+    return path.resolve(value);
+  }
+  return path.join(os.homedir(), '.claude');
+}
+
+function resolveOpenClawHome(explicitValue) {
+  const value = String(explicitValue || process.env.OPENCLAW_HOME || '').trim();
+  if (value !== '') {
+    return path.resolve(value);
+  }
+  return path.join(os.homedir(), '.openclaw');
+}
+
+function resolveOpenCodeConfigHome(explicitValue) {
+  const value = String(explicitValue || process.env.OPENCODE_CONFIG_HOME || '').trim();
+  if (value !== '') {
+    return path.resolve(value);
+  }
+
+  const xdgConfigHome = String(process.env.XDG_CONFIG_HOME || '').trim();
+  if (xdgConfigHome !== '') {
+    return path.join(path.resolve(xdgConfigHome), 'opencode');
+  }
+
+  return path.join(os.homedir(), '.config', 'opencode');
+}
+
+function listSkillDirectories(rootDir) {
+  if (!fs.existsSync(rootDir)) {
+    return [];
+  }
+
+  return fs.readdirSync(rootDir, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory())
+    .map((entry) => entry.name)
+    .sort();
+}
+
+function copyTree(sourceDir, targetDir) {
+  const sourceStat = fs.statSync(sourceDir);
+  if (!sourceStat.isDirectory()) {
+    throw new Error(`Skill source directory does not exist or is not a directory: ${sourceDir}`);
+  }
+
+  fs.mkdirSync(targetDir, { recursive: true });
+  for (const entry of fs.readdirSync(sourceDir, { withFileTypes: true })) {
+    const sourcePath = path.join(sourceDir, entry.name);
+    const targetPath = path.join(targetDir, entry.name);
+
+    if (entry.isDirectory()) {
+      copyTree(sourcePath, targetPath);
+      continue;
+    }
+
+    if (entry.isSymbolicLink()) {
+      const linkTarget = fs.readlinkSync(sourcePath);
+      fs.symlinkSync(linkTarget, targetPath);
+      continue;
+    }
+
+    fs.copyFileSync(sourcePath, targetPath);
+  }
+}
+
+function printSetupHelp() {
+  console.log('Usage: clawrise setup <client> [platform...]');
+  console.log('');
+  console.log('Supported clients: codex, claude-code, openclaw, opencode');
+  console.log('Supported platforms: feishu, notion');
+  console.log('');
+  console.log('Examples:');
+  console.log('  clawrise setup codex');
+  console.log('  clawrise setup codex feishu');
+  console.log('  clawrise setup claude-code notion --skills-dir ./.claude/skills');
+  console.log('  clawrise setup openclaw feishu --skills-dir ./skills');
+  console.log('  clawrise setup opencode notion --skills-dir ./.opencode/skills');
+}
+
+module.exports = {
+  handleSetupCommand,
+};

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@clawrise/clawrise-cli",
-  "version": "0.1.0-alpha.5",
-  "description": "Clawrise CLI with bundled first-party provider plugins.",
+  "version": "0.1.0-alpha.6",
+  "description": "Clawrise CLI with bundled first-party provider plugins and setup flows for AI client skills.",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -17,14 +17,24 @@
   "files": [
     "bin",
     "lib",
+    "skills",
     "README.md"
   ],
+  "keywords": [
+    "clawrise",
+    "cli",
+    "feishu",
+    "notion",
+    "codex",
+    "skills",
+    "setup"
+  ],
   "optionalDependencies": {
-    "@clawrise/clawrise-cli-darwin-arm64": "0.1.0-alpha.5",
-    "@clawrise/clawrise-cli-darwin-x64": "0.1.0-alpha.5",
-    "@clawrise/clawrise-cli-linux-arm64": "0.1.0-alpha.5",
-    "@clawrise/clawrise-cli-linux-x64": "0.1.0-alpha.5",
-    "@clawrise/clawrise-cli-win32-arm64": "0.1.0-alpha.5",
-    "@clawrise/clawrise-cli-win32-x64": "0.1.0-alpha.5"
+    "@clawrise/clawrise-cli-darwin-arm64": "0.1.0-alpha.6",
+    "@clawrise/clawrise-cli-darwin-x64": "0.1.0-alpha.6",
+    "@clawrise/clawrise-cli-linux-arm64": "0.1.0-alpha.6",
+    "@clawrise/clawrise-cli-linux-x64": "0.1.0-alpha.6",
+    "@clawrise/clawrise-cli-win32-arm64": "0.1.0-alpha.6",
+    "@clawrise/clawrise-cli-win32-x64": "0.1.0-alpha.6"
   }
 }

package/skills/clawrise-core/SKILL.md

@@ -0,0 +1,92 @@
+---
+name: clawrise-core
+description: Use when a task needs to use the local Clawrise CLI as an execution tool. This includes discovering platforms and operations, checking config and plugin health with doctor, inspecting auth methods, exporting specs, and executing third-party platform operations through `clawrise`. Pair with clawrise-feishu or clawrise-notion for platform-specific work.
+---
+
+# Clawrise Core
+
+Treat Clawrise as the local execution layer, not as a cross-platform business schema layer.
+
+This skill owns:
+
+- setup and environment checks
+- capability discovery through `doctor` and `spec`
+- auth and account inspection
+- generic execution rules
+
+This skill does not own:
+
+- Feishu-specific auth and task guidance
+- Notion-specific auth and task guidance
+- provider-specific field semantics beyond generic guardrails
+
+## Use This Skill When
+
+- You need to confirm that a local `clawrise` CLI is available
+- You need to run `setup <client> [platform...]`
+- You need to inspect plugins, config, runtime state, or playbooks
+- You need to discover available platforms or operations
+- You need to inspect the input fields, examples, or constraints of one operation
+- You need to execute a Clawrise operation
+
+## Workflow
+
+1. Prefer `clawrise` from `PATH`.
+2. If `clawrise` is not in `PATH`, but `npx` is available, use:
+
+```bash
+npx @clawrise/clawrise-cli ...
+```
+
+3. If the host still needs initial setup, run:
+
+```bash
+clawrise setup <client>
+clawrise setup <client> <platform>
+```
+
+or:
+
+```bash
+npx @clawrise/clawrise-cli setup <client>
+npx @clawrise/clawrise-cli setup <client> <platform>
+```
+
+4. If `clawrise` is not in `PATH`, but the current workspace is this repository, fall back to:
+
+```bash
+GOCACHE=/tmp/clawrise-go-build GOMODCACHE=/tmp/clawrise-gomodcache go run ./cmd/clawrise ...
+```
+
+5. Start with:
+
+```bash
+clawrise doctor
+```
+
+6. Then discover capabilities:
+
+```bash
+clawrise spec list
+clawrise spec list <path>
+clawrise spec get <operation>
+```
+
+7. Inspect auth only when the task needs it:
+
+```bash
+clawrise auth methods --platform <platform>
+clawrise auth inspect <account>
+clawrise auth check <account>
+```
+
+8. For write operations, always run `--dry-run` first and only perform the real call after the input shape is validated.
+
+9. When building input JSON, keep provider-native field names exactly as defined by the operation. Do not invent a unified cross-platform schema.
+
+10. If the task is Feishu-specific or Notion-specific, use the matching platform skill together with this one.
+
+## Read These References Only When Needed
+
+- `references/workflow.md`
+- `references/install-and-layout.md`

package/skills/clawrise-core/references/install-and-layout.md

@@ -0,0 +1,105 @@
+# Installation And Layout
+
+## 1. Repository Skill Source
+
+The source directories inside this repository are:
+
+```text
+skills/clawrise-core
+skills/clawrise-feishu
+skills/clawrise-notion
+```
+
+## 2. Client Skill Locations
+
+Default shared install targets are:
+
+```text
+~/.codex/skills/<skill-name>
+~/.claude/skills/<skill-name>
+~/.openclaw/skills/<skill-name>
+~/.config/opencode/skills/<skill-name>
+```
+
+Project-local installs may use client-specific directories such as:
+
+```text
+./.claude/skills/<skill-name>
+./skills/<skill-name>
+./.opencode/skills/<skill-name>
+```
+
+The exact target is selected by:
+
+```bash
+clawrise setup <client> [platform...]
+```
+
+or:
+
+```bash
+npx @clawrise/clawrise-cli setup <client> [platform...]
+```
+
+## 3. Default Clawrise Runtime Paths
+
+In this project, `clawrise doctor` exposes these default paths:
+
+- config file: `~/.clawrise/config.yaml`
+- state directory: `~/.clawrise/state`
+- runtime directory: `~/.clawrise/state/runtime`
+- repo-local plugin directory: `.clawrise/plugins`
+- user plugin directory: `~/.clawrise/plugins`
+
+Always trust the live `clawrise doctor` output over static assumptions.
+
+## 4. Plugin Install Sources
+
+Clawrise currently supports:
+
+- `file://`
+- `https://`
+- `npm://`
+
+Useful commands:
+
+```bash
+clawrise plugin list
+clawrise plugin install <source>
+clawrise plugin verify --all
+```
+
+## 5. Repository Install Script
+
+This repository provides:
+
+```bash
+./scripts/skills/setup-local-codex.sh
+```
+
+It copies the repository skills into a local Codex skill directory for repository-level testing.
+
+Restart Codex after installation so the new skills are loaded.
+
+## 6. No-Clone Distribution Options
+
+Recommended non-clone channels are:
+
+- website-hosted versioned skill archives
+- npm package bundled with the `skills/` directory
+
+For website distribution, publish:
+
+- a skill manifest such as `index.json`
+- versioned archives such as `<version>/<skill-name>.tar.gz`
+- one install script that downloads and expands skills into `~/.codex/skills`
+
+For npm distribution, prefer setup commands such as:
+
+```bash
+clawrise setup codex
+clawrise setup codex feishu
+clawrise setup claude-code notion --skills-dir ./.claude/skills
+```
+
+Do not use automatic `postinstall` hooks to write into the user's Codex directory.

package/skills/clawrise-core/references/workflow.md

@@ -0,0 +1,130 @@
+# Clawrise General Workflow
+
+## 1. Ensure Setup Has Been Run
+
+If the user is on a fresh machine or the current client has not been prepared yet, start with:
+
+```bash
+clawrise setup <client>
+clawrise setup <client> <platform>
+```
+
+or:
+
+```bash
+npx @clawrise/clawrise-cli setup <client>
+npx @clawrise/clawrise-cli setup <client> <platform>
+```
+
+Use platform setup only when the user actually needs that platform.
+
+Examples:
+
+- `setup codex`
+- `setup codex feishu`
+- `setup openclaw notion`
+
+## 2. Inspect The Environment First
+
+Start with:
+
+```bash
+clawrise doctor
+```
+
+This command tells you:
+
+- config file path
+- state and runtime paths
+- plugin discovery roots
+- discovered plugins and their health
+- playbook validation status
+
+Do not assume any of these before checking `doctor`:
+
+- a platform plugin is installed
+- a default account exists
+- local config is already complete
+
+## 3. Discover Before Building Input
+
+Preferred sequence:
+
+```bash
+clawrise spec list
+clawrise spec list feishu
+clawrise spec list notion
+clawrise spec get <operation>
+```
+
+If the task spans many operations, use:
+
+```bash
+clawrise spec export <path> --format markdown
+clawrise docs generate <path> --out-dir <dir>
+```
+
+`spec get` is the most important fact source when you need to build one concrete call.
+
+## 4. Inspect Auth And Accounts
+
+Useful commands:
+
+```bash
+clawrise auth methods --platform <platform>
+clawrise auth inspect <account>
+clawrise auth check <account>
+clawrise account list
+clawrise account inspect <name>
+```
+
+If the user does not explicitly provide an account, do not assume the default account is valid. Check `doctor` or `account current` first.
+
+## 5. Execution Rules
+
+Recommended order:
+
+```bash
+clawrise <operation> --dry-run --json '<payload>'
+clawrise <operation> --json '<payload>'
+```
+
+Common flags include:
+
+- `--account`
+- `--subject`
+- `--json`
+- `--input`
+- `--timeout`
+- `--dry-run`
+- `--idempotency-key`
+- `--quiet`
+
+## 6. Output Shape
+
+Execution output is a normalized JSON envelope. Key fields include:
+
+- `ok`
+- `operation`
+- `context`
+- `data`
+- `error`
+- `meta`
+- `idempotency`
+
+If a downstream step only needs the success payload, use `--quiet`.
+
+## 7. Architectural Boundary
+
+Clawrise unifies the execution layer, not the business resource model.
+
+That means:
+
+- Build Feishu inputs with Feishu-native fields
+- Build Notion inputs with Notion-native fields
+- Do not compress calendars, pages, documents, or records into one invented JSON schema
+
+If the user needs platform-specific auth or task guidance, switch to the matching platform skill after setup:
+
+- `clawrise-feishu`
+- `clawrise-notion`

package/skills/clawrise-feishu/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: clawrise-feishu
+description: Use when the task is to access Feishu through Clawrise, including Feishu auth setup, calendar events, docs updates, bitable records, wiki nodes, contacts, or any other `feishu.*` operation. Pair with clawrise-core.
+---
+
+# Clawrise Feishu
+
+This skill adds Feishu-specific guidance. Use `clawrise-core` for the common execution workflow.
+
+This skill assumes that the current client has already been prepared with:
+
+```bash
+clawrise setup <client> feishu
+```
+
+or:
+
+```bash
+npx @clawrise/clawrise-cli setup <client> feishu
+```
+
+## Usage
+
+1. Start with the `clawrise-core` workflow to inspect the local environment and specs.
+2. Add this skill only when the task is Feishu-specific.
+3. Do not use this skill to explain generic client setup unless the user is explicitly setting up Feishu support.
+
+## Check These First
+
+```bash
+clawrise spec list feishu
+clawrise auth methods --platform feishu
+```
+
+## Auth Constraints
+
+- `feishu.app_credentials`
+  - for `bot`
+- `feishu.oauth_user`
+  - for `user`
+
+If the user does not explicitly say whether the task should use a bot or a user identity, do not guess. Inspect the account config and auth method first.
+
+## Task Rules
+
+- Run `clawrise spec get <operation>` before building JSON
+- Prefer `--dry-run` for write operations
+- Read before write to avoid overwriting existing data
+- Prefer RFC3339 for time fields
+
+## Read This Reference Only When The Task Matches
+
+- `references/common-tasks.md`

package/skills/clawrise-feishu/references/common-tasks.md

@@ -0,0 +1,80 @@
+# Feishu Common Tasks
+
+This reference assumes that `clawrise-core` and `clawrise-feishu` have already been installed for the current client.
+
+If the user still needs Feishu support installed, run:
+
+```bash
+clawrise setup <client> feishu
+```
+
+## Auth Methods
+
+Current Feishu auth methods include:
+
+- `feishu.app_credentials`
+  - `subject=bot`
+  - requires `app_id` and `app_secret`
+- `feishu.oauth_user`
+  - `subject=user`
+  - requires `client_id` and `client_secret`
+  - supports interactive login
+
+Check first:
+
+```bash
+clawrise auth methods --platform feishu
+```
+
+## High-Signal Tasks
+
+### 1. Create Or Update A Feishu Calendar Event
+
+Start with:
+
+- `feishu.calendar.event.create`
+- `feishu.calendar.event.get`
+- `feishu.calendar.event.update`
+
+Playbook:
+
+- `docs/playbooks/en/feishu-calendar-event-upsert.md`
+
+### 2. Update A Feishu Document
+
+Start with:
+
+- `feishu.docs.document.get`
+- `feishu.docs.document.get_raw_content`
+- `feishu.docs.document.edit`
+
+Playbook:
+
+- `docs/playbooks/en/feishu-document-update.md`
+
+### 3. Create Or Update A Feishu Bitable Record
+
+Start with:
+
+- `feishu.bitable.record.list`
+- `feishu.bitable.record.create`
+- `feishu.bitable.record.update`
+
+Playbook:
+
+- `docs/playbooks/en/feishu-bitable-record-upsert.md`
+
+## Suggested Flow
+
+For any concrete task, prefer:
+
+```bash
+clawrise spec get <operation>
+clawrise <operation> --dry-run --json '<payload>'
+```
+
+If the user describes a business intent without naming the operation, start with:
+
+```bash
+clawrise spec list feishu
+```

package/skills/clawrise-notion/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: clawrise-notion
+description: Use when the task is to access Notion through Clawrise, including Notion auth setup, page updates, markdown updates, data source queries, comments, blocks, or any other `notion.*` operation. Pair with clawrise-core.
+---
+
+# Clawrise Notion
+
+This skill adds Notion-specific guidance. Use `clawrise-core` for the common execution workflow.
+
+This skill assumes that the current client has already been prepared with:
+
+```bash
+clawrise setup <client> notion
+```
+
+or:
+
+```bash
+npx @clawrise/clawrise-cli setup <client> notion
+```
+
+## Usage
+
+1. Start with the `clawrise-core` workflow to inspect the local environment and specs.
+2. Add this skill only when the task is Notion-specific.
+3. Do not use this skill to explain generic client setup unless the user is explicitly setting up Notion support.
+
+## Check These First
+
+```bash
+clawrise spec list notion
+clawrise auth methods --platform notion
+```
+
+## Auth Constraints
+
+- `notion.internal_token`
+  - for `integration`
+- `notion.oauth_public`
+  - for `integration`
+
+Both current Notion auth methods use the `integration` subject. Do not switch to `bot` or `user`.
+
+## Task Rules
+
+- Run `clawrise spec get <operation>` before building JSON
+- Prefer `--dry-run` for write operations
+- Read before write to avoid overwriting page or block content
+- Keep pages, blocks, comments, and data sources in Notion-native fields
+
+## Read This Reference Only When The Task Matches
+
+- `references/common-tasks.md`

package/skills/clawrise-notion/references/common-tasks.md

@@ -0,0 +1,68 @@
+# Notion Common Tasks
+
+This reference assumes that `clawrise-core` and `clawrise-notion` have already been installed for the current client.
+
+If the user still needs Notion support installed, run:
+
+```bash
+clawrise setup <client> notion
+```
+
+## Auth Methods
+
+Current Notion auth methods include:
+
+- `notion.internal_token`
+  - `subject=integration`
+  - requires `token`
+- `notion.oauth_public`
+  - `subject=integration`
+  - requires `client_id` and `client_secret`
+  - supports interactive login
+
+Check first:
+
+```bash
+clawrise auth methods --platform notion
+```
+
+## High-Signal Tasks
+
+### 1. Update A Page Title, Properties, Or Body
+
+Start with:
+
+- `notion.page.get`
+- `notion.page.update`
+- `notion.page.markdown.get`
+- `notion.page.markdown.update`
+
+Playbook:
+
+- `docs/playbooks/en/notion-page-update.md`
+
+### 2. Query A Data Source
+
+Start with:
+
+- `notion.data_source.get`
+- `notion.data_source.query`
+
+Playbook:
+
+- `docs/playbooks/en/notion-data-source-query.md`
+
+## Suggested Flow
+
+For any concrete task, prefer:
+
+```bash
+clawrise spec get <operation>
+clawrise <operation> --dry-run --json '<payload>'
+```
+
+If the user describes a business intent without naming the operation, start with:
+
+```bash
+clawrise spec list notion
+```