qiongli 1.12.0 → 1.13.0

package/README.md

@@ -1,30 +1,36 @@
 # qiongli
 
-`qiongli` is the npm/npx installer for the Qiongli academic workflow skills.
+`qiongli` on npm is the Python-free asset manager for Qiongli client assets.
 
 ## Install
 
 ```bash
 npm install -g qiongli
 qiongli setup
-qiongli install --target all
+qiongli install --target all --surface skills
+qiongli check --json
 qiongli project init --project-dir .
 qiongli project set-subject finance --project-dir .
 qiongli project status --project-dir .
 ```
 
-`qiongli setup` uses the bundled Python bridge and requires Python 3.12+ with `PyYAML`.
-Use explicit `qiongli install ...` commands when you only need Node-based asset installation. For normal CLI/local plugin use, install once and keep per-project subject behavior in `.qiongli/guidance_manifest.yaml`.
+`qiongli setup` is npm asset setup. It stays on the Python-free asset manager path and installs client assets only. For full runtime commands such as `doctor`, `mcp serve`, `provider setup`, `task-run`, or `customize`, install the full runtime first:
+
+```bash
+pipx install qiongli
+```
+
+Use explicit `qiongli install ...` commands when you only need scripted asset installation. For normal asset/project use, install once and keep per-project subject behavior in `.qiongli/guidance_manifest.yaml`.
 
 Update an existing global install with:
 
 ```bash
 qiongli update
-qiongli update --dry-run
-qiongli update --yes
+qiongli refresh
+qiongli upgrade --target all
 ```
 
-Use `qiongli update` for the normal interactive update flow. It checks whether the installed qiongli CLI/package has a newer release, asks before running the package-manager update, then asks whether to refresh installed local plugins/assets from the new package. Use `qiongli update --yes` for CI or scripts; it answers both prompts as yes. Use `qiongli update --no-refresh` when you only want the CLI/package update and plan to run `qiongli install ...` yourself.
+`qiongli update`, `qiongli refresh`, and `qiongli upgrade` all reapply bundled assets from the currently installed npm package. `upgrade` is treated as an overwrite refresh. They do not update the npm package or the full Python CLI. Selected release archives, package self-update, and `qiongli self-update` require the full runtime: `pipx install qiongli`.
 
 Or run without a global install:
 
@@ -51,15 +57,15 @@ qiongli uninstall --target codex
 
 The npm package contains pre-materialized `core`, `economics`, `accounting`, `business`, `finance`, `political-economy`, `geoeconomics`, and `economics-accounting` `qiongli-workflow` subject payloads in both `complete` and `focused` coverage. It does not depend on PyPI for skill installation and does not run `postinstall`.
 
-`qiongli setup` is the interactive guided path for choosing install or upgrade, runtime surface, subject, coverage, `--mode copy|link`, install scope, CLI directory, `--overwrite` / `--no-overwrite`, optional upgrade source, literature provider setup, and doctor verification. Provider setup defaults to one local browser page with key-access guidance for OpenAlex, Semantic Scholar, Crossref, PubMed, and arXiv; use `--provider-mode prompt` for terminal-only entry or `--provider-mode skip` to bypass it. Each prompt includes a short `Tip:` comment. It delegates to the bundled Python bridge, so it requires Python 3.12+ with `PyYAML`. If you only need Node-based asset installation, use explicit `qiongli install ...` commands.
+`qiongli setup` in the npm package is client-asset setup only. It uses the same Python-free asset path as `qiongli install`, `qiongli update`, `qiongli refresh`, and `qiongli project ...`. The interactive setup wizard, provider setup, doctor checks, and full MCP/orchestrator commands require the full runtime: `pipx install qiongli`.
 
 ## Global-first update model
 
 The npm package and the installed workflow assets are separate surfaces:
 
 - `npm install -g qiongli@latest` updates the npm CLI and bundled payload in npm's global package location.
-- `qiongli update --yes` performs that npm package update and then refreshes installed full local plugin/MCP surfaces from the new bundled payload.
-- `qiongli install --target all` installs the stable full local runtime used across projects.
+- `qiongli update`, `qiongli refresh`, and `qiongli upgrade` reapply bundled assets from the current npm package; they do not update the npm package.
+- `qiongli install --target all` installs the stable skills surface used across projects. Plugin-lite output is opt-in with `--surface plugin` or `--surface both` where bundled and supported.
 - `qiongli project init --project-dir .` creates `.qiongli/guidance_manifest.yaml` for a project.
 - `qiongli project set-subject finance --project-dir .` changes ordinary project subject behavior without reinstalling a package.
 - Missing `.qiongli/guidance_manifest.yaml` means implicit `active_subject: auto`: Qiongli uses core guidance, infers temporary subject or method lenses from the task, and writes auditable proposals before changing project-local state.
@@ -91,17 +97,18 @@ Global assets are written under client home directories such as:
 ~/.hermes/skills/qiongli-workflow
 ```
 
-Advanced bridge commands such as `setup`, `doctor`, `task-run`, and `team-run` use the Python runtime bundled in the npm package and require Python 3.12+ with `PyYAML`.
+Transitional `python-runtime/` files still ship in the npm package for compatibility checks, but npm CLI dispatch stays on the Python-free asset path. Full runtime commands such as `doctor`, `task-run`, `team-run`, `mcp serve`, `provider setup`, and `customize` require `pipx install qiongli`.
 
 ## MCP server
 
-`qiongli mcp serve --transport stdio` is the unified full CLI MCP server. It exposes literature provider tools plus orchestrator and task-run tools from one server. The zero-dependency Node literature-provider MCP bundled by plugins remains a marketplace/MCPB fallback for environments that cannot run the full CLI.
+`qiongli mcp serve --transport stdio` is the unified full CLI MCP server. It exposes literature provider tools plus orchestrator and task-run tools from one server. The zero-dependency Node literature-provider MCP bundled by plugins remains a marketplace/MCPB fallback for environments that do not need the full runtime.
 
-The Python CLI path (`qiongli install --profile full --target codex`) performs managed Codex MCP registration for the unified server. The npm asset installer stays conservative: explicit npm installs can report MCP guidance with `qiongli install --parts globals,mcp --dry-run`, but they do not rewrite client MCP config.
+The full runtime path (`pipx install qiongli`, then `qiongli install --profile full --target codex`) performs managed Codex MCP registration for the unified server. The npm asset installer stays conservative: explicit npm installs can report MCP guidance with `qiongli install --parts globals,mcp --dry-run`, but they do not run the full server or rewrite client MCP config.
 
-The npm launcher also delegates MCP commands to the bundled Python bridge:
+Install the full runtime before running MCP commands:
 
 ```bash
+pipx install qiongli
 qiongli mcp serve --transport stdio
 qiongli mcp doctor --json
 qiongli mcp config example --target codex --json

package/lib/args.mjs

@@ -1,16 +1,13 @@
 const TARGETS = new Set(['codex', 'claude', 'antigravity', 'hermes', 'all']);
 const MODES = new Set(['copy', 'link']);
-const BRIDGE_COMMANDS = new Set(['doctor', 'guidance', 'task-run', 'team-run', 'parallel', 'chain', 'role', 'single', 'code-build', 'task-plan']);
-const PYTHON_CLI_COMMANDS = new Set(['setup', 'mcp', 'self-update', 'update']);
+const SURFACES = new Set(['skills', 'plugin', 'both']);
+const REFRESH_COMMANDS = new Set(['upgrade', 'refresh', 'update']);
 
 export function parseArgv(argv) {
   const [rawCommand = 'help', ...restArgs] = argv;
-  if (BRIDGE_COMMANDS.has(rawCommand) || PYTHON_CLI_COMMANDS.has(rawCommand)) {
-    return { command: rawCommand, options: {}, rest: restArgs };
-  }
 
   let command = rawCommand;
-  if (rawCommand === 'upgrade') {
+  if (REFRESH_COMMANDS.has(rawCommand)) {
     command = 'install';
   } else if (rawCommand === 'uninstall' || rawCommand === 'delete') {
     command = 'remove';
@@ -19,17 +16,34 @@ export function parseArgv(argv) {
     target: 'all',
     mode: 'copy',
     projectDir: '.',
-    overwrite: rawCommand === 'upgrade',
+    surface: 'skills',
+    overwrite: REFRESH_COMMANDS.has(rawCommand),
     dryRun: false,
     json: false,
     globals: false,
     subject: 'core',
     coverage: 'complete',
     parts: '',
+    projectCommand: '',
+    projectSubject: '',
   };
   const rest = [];
+  let i = 0;
 
-  for (let i = 0; i < restArgs.length; i += 1) {
+  if (command === 'project' && restArgs[0] && !restArgs[0].startsWith('--')) {
+    options.projectCommand = restArgs[0];
+    i = 1;
+    if (
+      options.projectCommand === 'set-subject'
+      && restArgs[i]
+      && !restArgs[i].startsWith('--')
+    ) {
+      options.projectSubject = restArgs[i];
+      i += 1;
+    }
+  }
+
+  for (; i < restArgs.length; i += 1) {
     const arg = restArgs[i];
     if (arg === '--target') {
       options.target = requireValue(restArgs, i, arg);
@@ -37,11 +51,19 @@ export function parseArgv(argv) {
     } else if (arg === '--mode') {
       options.mode = requireValue(restArgs, i, arg);
       i += 1;
+    } else if (arg === '--surface') {
+      options.surface = requireValue(restArgs, i, arg);
+      i += 1;
     } else if (arg === '--project-dir') {
       options.projectDir = requireValue(restArgs, i, arg);
       i += 1;
     } else if (arg === '--subject') {
-      options.subject = requireValue(restArgs, i, arg);
+      const value = requireValue(restArgs, i, arg);
+      if (command === 'project' && options.projectCommand === 'set-subject') {
+        options.projectSubject = value;
+      } else {
+        options.subject = value;
+      }
       i += 1;
     } else if (arg === '--coverage') {
       options.coverage = requireValue(restArgs, i, arg);
@@ -73,6 +95,9 @@ export function parseArgv(argv) {
   if (options.mode && !MODES.has(options.mode)) {
     throw new Error(`Unsupported mode: ${options.mode}`);
   }
+  if (options.surface && !SURFACES.has(options.surface)) {
+    throw new Error(`Unsupported surface: ${options.surface}`);
+  }
   return { command, options, rest };
 }
 

package/lib/cli.mjs

@@ -1,25 +1,24 @@
 import { parseArgv } from './args.mjs';
 import { packageRoot } from './package-root.mjs';
 import { buildCheck, cleanAssets, installSkills, removeAssets } from './installer.mjs';
+import { initProject, projectStatus, renderProjectResult, setProjectSubject } from './project.mjs';
 import {
-  checkPythonRuntime,
-  runBridgeCommand as defaultRunBridgeCommand,
-  runPythonCliCommand as defaultRunPythonCliCommand,
-} from './python-runtime.mjs';
+  FULL_RUNTIME_COMMANDS,
+  hasLegacyUpdateFlags,
+  writeFullRuntimeRequired,
+  writeLegacyUpdateFlagGuidance,
+} from './runtime-message.mjs';
 
-const BRIDGE_COMMANDS = new Set(['doctor', 'guidance', 'task-run', 'team-run', 'parallel', 'chain', 'role', 'single', 'code-build', 'task-plan']);
-const PYTHON_CLI_COMMANDS = new Set(['setup', 'mcp', 'self-update', 'update']);
-const SELF_UPDATE_COMMANDS = new Set(['self-update', 'update']);
+const INSTALL_COMMANDS = new Set(['install', 'setup']);
 
 export async function main(argv, {
   stdout = process.stdout,
   stderr = process.stderr,
   env = process.env,
   packageRoot: packageRootOverride,
-  runBridgeCommand = defaultRunBridgeCommand,
-  runPythonCliCommand = defaultRunPythonCliCommand,
 } = {}) {
   const root = packageRootOverride || packageRoot();
+  const [rawCommand = 'help'] = argv;
   let parsed;
   try {
     parsed = parseArgv(argv);
@@ -33,13 +32,23 @@ export async function main(argv, {
     return 0;
   }
 
-  if (parsed.command === 'install') {
+  if (rawCommand === 'update' && hasLegacyUpdateFlags(parsed.rest)) {
+    writeLegacyUpdateFlagGuidance(stderr);
+    return 1;
+  }
+
+  if (INSTALL_COMMANDS.has(parsed.command)) {
+    if (parsed.rest.length) {
+      writeUnsupportedAssetArguments(parsed.rest, stderr);
+      return 2;
+    }
     let result;
     try {
       result = installSkills({
         packageRoot: root,
         target: parsed.options.target,
         mode: parsed.options.mode,
+        surface: parsed.options.surface,
         overwrite: parsed.options.overwrite,
         dryRun: parsed.options.dryRun,
         subject: parsed.options.subject,
@@ -61,6 +70,7 @@ export async function main(argv, {
       result = removeAssets({
         target: parsed.options.target,
         projectDir: parsed.options.projectDir,
+        surface: parsed.options.surface,
         parts: parsed.options.parts,
         dryRun: parsed.options.dryRun,
         env,
@@ -78,7 +88,8 @@ export async function main(argv, {
     try {
       payload = {
         ...buildCheck({ packageRoot: root, subject: parsed.options.subject, coverage: parsed.options.coverage, env }),
-        python_bridge: checkPythonRuntime(),
+        python_bridge: pythonBridgeStatus(),
+        npm_cli: npmCliStatus(),
       };
     } catch (error) {
       stderr.write(`[qiongli] ${error.message}\n`);
@@ -91,7 +102,8 @@ export async function main(argv, {
       stdout.write(`Payload version: ${payload.payload.version || '<unknown>'}\n`);
       stdout.write(`Payload subject: ${payload.payload.subject || '<unknown>'}\n`);
       stdout.write(`Payload coverage: ${payload.payload.coverage || '<unknown>'}\n`);
-      stdout.write(`Python bridge: ${payload.python_bridge.ok ? 'ok' : 'warn'} - ${payload.python_bridge.message}\n`);
+      stdout.write(`Npm CLI: ${payload.npm_cli.role} (${payload.npm_cli.python_free ? 'Python-free' : 'Python required'})\n`);
+      stdout.write(`Full runtime: ${payload.npm_cli.full_runtime_install}\n`);
     }
     return 0;
   }
@@ -112,26 +124,52 @@ export async function main(argv, {
       stderr.write('[qiongli] runtime supports only: doctor\n');
       return 2;
     }
-    const result = checkPythonRuntime();
-    stdout.write(`${result.ok ? '[ok]' : '[warn]'} ${result.message}\n`);
-    if (result.hint) {
-      stdout.write(`Hint: ${result.hint}\n`);
-    }
-    return result.ok ? 0 : 1;
+    stdout.write('[ok] Qiongli npm asset manager is installed.\n');
+    stdout.write('Full runtime: pipx install qiongli\n');
+    return 0;
   }
 
-  if (PYTHON_CLI_COMMANDS.has(parsed.command)) {
-    const childEnv = SELF_UPDATE_COMMANDS.has(parsed.command)
-      ? { ...env, QIONGLI_INSTALL_CHANNEL: 'npm' }
-      : env;
-    return runPythonCliCommand({ packageRoot: root, args: [parsed.command, ...parsed.rest], env: childEnv });
+  if (parsed.command === 'project') {
+    let result;
+    try {
+      if (parsed.options.projectCommand === 'init') {
+        result = initProject({
+          projectDir: parsed.options.projectDir,
+          dryRun: parsed.options.dryRun,
+        });
+      } else if (parsed.options.projectCommand === 'status') {
+        result = {
+          action: 'status',
+          changed: false,
+          dry_run: false,
+          state: projectStatus({ projectDir: parsed.options.projectDir }),
+          actions: [],
+        };
+      } else if (parsed.options.projectCommand === 'set-subject') {
+        if (!parsed.options.projectSubject) {
+          stderr.write('[qiongli] project set-subject requires a subject\n');
+          return 2;
+        }
+        result = setProjectSubject({
+          projectDir: parsed.options.projectDir,
+          subject: parsed.options.projectSubject,
+          dryRun: parsed.options.dryRun,
+        });
+      } else {
+        stderr.write('[qiongli] project supports: init, status, set-subject\n');
+        return 2;
+      }
+    } catch (error) {
+      stderr.write(`[qiongli] ${error.message}\n`);
+      return 2;
+    }
+    stdout.write(renderProjectResult(result, { json: parsed.options.json }));
+    return 0;
   }
 
-  if (BRIDGE_COMMANDS.has(parsed.command)) {
-    const args = parsed.command === 'doctor' && !parsed.rest.includes('--cwd')
-      ? ['--cwd', parsed.options.cwd || '.', ...parsed.rest]
-      : parsed.rest;
-    return runBridgeCommand({ packageRoot: root, command: parsed.command, args });
+  if (FULL_RUNTIME_COMMANDS.has(parsed.command)) {
+    writeFullRuntimeRequired(parsed.command, stderr);
+    return 1;
   }
 
   stderr.write(`[qiongli] unknown command: ${parsed.command}\n`);
@@ -139,7 +177,7 @@ export async function main(argv, {
 }
 
 function printInstallResult(result, stdout) {
-  stdout.write('Qiongli npm installer\n');
+  stdout.write('Qiongli npm asset manager\n');
   stdout.write(`source version: ${result.sourceVersion || '<unknown>'}\n`);
   stdout.write(`source subject: ${result.sourceSubject || '<unknown>'}\n`);
   stdout.write(`source coverage: ${result.sourceCoverage || '<unknown>'}\n`);
@@ -161,37 +199,56 @@ function printRemoveResult(result, stdout) {
 }
 
 function helpText() {
-  return `Qiongli npm installer
+  return `Qiongli npm asset manager
 
 Usage:
-  qiongli install --subject core --target all
+  qiongli install --subject core --target all [--surface skills]
+  qiongli setup --target codex [--surface skills] [--dry-run]
+  qiongli update --target all [--dry-run]
+  qiongli refresh --target all [--dry-run]
   qiongli upgrade --subject economics --coverage complete --target all
   qiongli remove [--target all]
   qiongli uninstall [--target codex]
   qiongli check [--json]
   qiongli clean --project-dir . [--globals]
+  qiongli project init --project-dir . [--dry-run] [--json]
+  qiongli project status --project-dir . [--json]
+  qiongli project set-subject <subject> --project-dir . [--dry-run] [--json]
   qiongli runtime doctor
-  qiongli self-update [--channel stable|next] [--yes]
-  qiongli update [--dry-run]
-  qiongli setup [--dry-run] [--project-dir .] [--no-doctor]
-  qiongli mcp serve --transport stdio
-  qiongli mcp doctor --json
-  qiongli mcp upgrade --target all [--dry-run]
-  qiongli doctor --cwd .
-  qiongli guidance init [--project-dir .]
-  qiongli guidance show|trace [--project-dir .]
-  qiongli guidance apply --proposal .qiongli/trace/runs/<run_id>/guidance_update_proposal.md
-  qiongli task-run ...
-  qiongli team-run ...
+
+Full runtime commands require \`pipx install qiongli\`:
+  doctor|task-run|team-run|parallel|chain|role|single|code-build|task-plan|mcp|provider|guidance|customize|init|align
 
 Options:
   --target codex|claude|antigravity|hermes|all
-  --subject core|economics|accounting|business|finance|economics-accounting
+  --surface skills|plugin|both
+  --subject core|economics|accounting|business|finance|political-economy|geoeconomics|economics-accounting
   --coverage complete|focused
   --mode copy|link
   --parts globals,project,cli,mcp
   --overwrite
   --dry-run
-  --no-doctor
 `;
 }
+
+function npmCliStatus() {
+  return {
+    role: 'asset-manager',
+    python_free: true,
+    full_runtime_install: 'pipx install qiongli',
+  };
+}
+
+function pythonBridgeStatus() {
+  return {
+    deprecated: true,
+    bundled: false,
+    managed_by_npm: false,
+    message: 'Not bundled or managed by this npm asset-manager path.',
+  };
+}
+
+function writeUnsupportedAssetArguments(args, stderr) {
+  stderr.write(`[qiongli] unsupported npm asset-manager argument: ${args[0]}\n`);
+  stderr.write('[qiongli] Full runtime setup/update/archive options require: pipx install qiongli\n');
+}