@minhpnq1807/contextos 0.5.6 → 0.5.8

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## 0.5.8
+
+- Adds explicit `ctx setup` interactive onboarding for installing agents, enabling injection, syncing Ruler rules/MCP servers, and syncing skills through skillshare.
+- Adds non-interactive setup flags: `--yes`, `--agents`, `--no-rules`, `--no-skills`, `--quiet`, and `--no-inject`.
+- Keeps npm install lifecycle clean; setup only runs when the user explicitly invokes `ctx setup`.
+
+## 0.5.7
+
+- Adds thin passthrough commands `ctx ruler -- <args>` and `ctx skillshare -- <args>` for upstream admin/debug workflows without reimplementing those CLIs.
+- Preserves upstream output and exit status for passthrough commands, with install hints when the upstream binary is missing.
+
 ## 0.5.6
 
 - Adds visible `ctx install` progress from 0-100 so long model/file/skill embedding warmups no longer look stalled.

package/README.md

@@ -11,10 +11,25 @@ Published package: [`@minhpnq1807/contextos`](https://www.npmjs.com/package/@min
 ```bash
 npm install -g @minhpnq1807/contextos
 ctx --version
-ctx install
+ctx setup
 ```
 
-Restart Codex after installing, then use Codex normally. ContextOS runs through Codex hooks and the `ctx-mcp` MCP server.
+`ctx setup` is the recommended first-run flow. It asks which agents to configure, whether prompt context injection should be enabled, whether to sync project rules/MCP through Ruler, and whether to sync skills through skillshare. It only runs when you explicitly invoke it; npm install does not run setup automatically.
+
+For scriptable installs, use:
+
+```bash
+ctx setup --yes
+ctx setup --yes --agents codex,claude,agy
+```
+
+Restart your agent after setup, then use it normally. ContextOS runs through agent hooks and the `ctx-mcp` MCP server.
+
+Codex-only install is still available:
+
+```bash
+ctx install
+```
 
 Claude Code and Antigravity are supported through their native hook systems:
 
@@ -27,6 +42,7 @@ You can also run without a global install:
 
 ```bash
 npx @minhpnq1807/contextos@latest install
+npx @minhpnq1807/contextos@latest setup
 npx @minhpnq1807/contextos@latest install claude
 npx @minhpnq1807/contextos@latest install agy
 ```
@@ -269,6 +285,20 @@ ctx sync --rules --no-import-codex-mcp
 
 `ctx sync --rules` is project-scoped. It writes `.ruler/ruler.toml` in the current project and lets Ruler generate agent files from that project source of truth. ContextOS runtime history still follows the project-path isolation model described below.
 
+## Upstream Passthrough
+
+ContextOS exposes thin passthrough commands for Ruler and skillshare admin/debug workflows:
+
+```bash
+ctx ruler -- apply --agents codex,claude,antigravity
+ctx ruler -- init
+ctx skillshare -- status
+ctx skillshare -- target list
+ctx skillshare -- doctor
+```
+
+Everything after `--` is forwarded unchanged to the upstream CLI. ContextOS does not reinterpret those args, and it preserves the upstream output and exit status. Use `ctx sync --rules` and `ctx sync --skills` for ContextOS-managed workflows; use passthrough when you need a native Ruler or skillshare command.
+
 ## Troubleshooting
 
 ### `ctx-mcp bridge socket not found`
@@ -309,6 +339,12 @@ This warning comes from a transitive dependency in the local embedding/WASM stac
 | `ctx install --quiet` | Installs ContextOS in measurement-only mode. | You want reports and stats but do not want visible injected context. | Installs the same hooks, but prompt hooks return empty context. |
 | `ctx install --inject` | Installs ContextOS with explicit injection mode. | You want to be explicit in scripts or docs. | Same runtime behavior as the default install mode; if combined with `--quiet`, `--inject` wins. |
 | `ctx install --copy` | Copies only the plugin payload to `$CODEX_HOME/plugins/ctx`. | Local development or manual plugin experiments. | Does not register marketplace, MCP, or global hooks. |
+| `ctx setup` | Runs the first-run setup wizard. | You want the recommended onboarding flow after `npm install -g @minhpnq1807/contextos`. | Installs selected agents, optionally syncs Ruler rules/MCP and skillshare skills, then prints next steps. |
+| `ctx setup --yes` | Runs setup with defaults non-interactively. | You want scriptable all-agent setup. | Uses `codex,claude,agy`, enables injection, syncs rules, syncs skills, and passes `--yes` to dependency setup prompts. |
+| `ctx setup --agents <list>` | Runs setup for selected agents. | You want only part of the default set. | Accepts comma-separated `codex`, `claude`, `agy`, or `antigravity`. |
+| `ctx setup --no-rules` | Skips Ruler sync during setup. | You only want hooks/MCP install and maybe skill sync. | Does not run `ctx sync --rules`. |
+| `ctx setup --no-skills` | Skips skillshare sync during setup. | You do not want shared skills configured. | Does not run `ctx sync --skills`. |
+| `ctx setup --quiet` | Runs setup in measurement-only mode. | You want reports/stats without visible injected prompt context. | Installs hooks with prompt context injection disabled. |
 | `ctx debug -- "task"` | Runs the scheduler locally for a fake prompt. | You want to see which AGENTS.md rules and files ContextOS would inject before using Codex. | Prints rule scores, scoring reasons, suggested files, and final `additionalContext`. |
 | `ctx report` | Shows the last Stop-hook compliance report for the current workspace. | An agent task has finished and you want the summary again. | Reads `~/.ctx/contextos/workspaces/<workspace-id>/last-report.json`. |
 | `ctx evidence` | Shows detailed evidence behind the last report for the current workspace. | You want to inspect why a rule was marked `followed`, `ignored`, or `unknown`. | Prints rule text, source file, score, status, and evidence reason. |
@@ -324,6 +360,8 @@ This warning comes from a transitive dependency in the local embedding/WASM stac
 | `ctx sync --skills --dry-run` | Previews skillshare sync. | You want to inspect behavior before changing skill directories. | Runs `skillshare sync --dry-run` and skips embedding rebuild. |
 | `ctx sync --skills --no-collect` | Skips collecting existing agent skills into skillshare. | You already manage `~/.config/skillshare/skills` and only want to push it out. | Initializes/syncs skillshare without running `skillshare backup` or `skillshare collect --all`. |
 | `ctx embeddings warm -- "task"` | Prepares local semantic embedding caches. | First install, CI smoke checks, or after changing AGENTS.md/project files/skills. | Loads/downloads `Xenova/all-MiniLM-L6-v2` and writes rule, file-path, and skill vectors to `~/.ctx/contextos/embeddings.db`. |
+| `ctx ruler -- <args>` | Forwards args to the installed `ruler` CLI. | You need native Ruler commands such as `init`, `apply`, or `revert`. | Preserves Ruler stdout/stderr and exit status. |
+| `ctx skillshare -- <args>` | Forwards args to the installed `skillshare` CLI. | You need native skillshare commands such as `status`, `target list`, `doctor`, `push`, or `pull`. | Preserves skillshare stdout/stderr and exit status. |
 | `ctx --version` | Prints the installed ContextOS CLI version. | You want to confirm which npm version is being executed. | Prints the version from package metadata. |
 
 ## Runtime Files

package/bin/ctx.js

@@ -1,6 +1,8 @@
 #!/usr/bin/env node
 import fs from "node:fs";
 import path from "node:path";
+import readline from "node:readline/promises";
+import { stdin as input, stdout as output } from "node:process";
 import { fileURLToPath } from "node:url";
 import { execFileSync } from "node:child_process";
 
@@ -24,6 +26,8 @@ import { installAntigravityMcp } from "../plugins/ctx/lib/antigravity-mcp.js";
 import { syncRules } from "../plugins/ctx/lib/ruler-sync.js";
 import { syncSkills } from "../plugins/ctx/lib/skillshare-sync.js";
 import { scanSkills, warmSkillEmbeddings } from "../plugins/ctx/lib/skill-discoverer.js";
+import { parsePassthroughArgs, runPassthrough } from "../plugins/ctx/lib/passthrough.js";
+import { parseAgentList, parseSetupArgs, setupSummaryLines } from "../plugins/ctx/lib/setup-wizard.js";
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const rootDir = path.resolve(__dirname, "..");
@@ -41,6 +45,12 @@ Usage:
   ctx install --quiet
   ctx install --inject
   ctx install --copy
+  ctx setup
+  ctx setup --yes
+  ctx setup --agents codex,claude,agy
+  ctx setup --no-rules
+  ctx setup --no-skills
+  ctx setup --quiet
   ctx debug -- "task"
   ctx report
   ctx evidence
@@ -55,6 +65,8 @@ Usage:
   ctx sync --skills --no-collect
   ctx sync --skills --agents codex,claude,antigravity
   ctx embeddings warm -- "task"
+  ctx ruler -- <ruler args>
+  ctx skillshare -- <skillshare args>
   ctx --version
 `;
 }
@@ -391,6 +403,96 @@ async function warmEmbeddings(task) {
   console.log(`Cache: ${result.cachePath}`);
 }
 
+function printSetupBanner() {
+  console.log("");
+  console.log("╭─ ContextOS setup ─────────────────────────────────────────╮");
+  console.log("│ Task-aware rules, MCP sync, and skill discovery for agents │");
+  console.log("╰───────────────────────────────────────────────────────────╯");
+  console.log("");
+}
+
+async function askSetupQuestion(rl, question, defaultValue) {
+  const suffix = defaultValue ? ` (${defaultValue})` : "";
+  const answer = await rl.question(`◇ ${question}${suffix}: `);
+  return answer.trim() || defaultValue;
+}
+
+async function askSetupYesNo(rl, question, defaultValue = true) {
+  const suffix = defaultValue ? "Y/n" : "y/N";
+  const answer = await askSetupQuestion(rl, question, suffix);
+  if (!answer || answer === suffix) return defaultValue;
+  return !/^n(o)?$/i.test(answer.trim());
+}
+
+async function setup({ args = [], cwd = process.cwd() } = {}) {
+  const options = parseSetupArgs(args);
+  const interactive = !options.yes && process.stdin.isTTY;
+
+  printSetupBanner();
+  console.log(`◇ Installation directory:\n│  ${cwd}`);
+
+  if (interactive) {
+    const rl = readline.createInterface({ input, output });
+    try {
+      const proceed = await askSetupYesNo(rl, "Install to this directory?", true);
+      if (!proceed) {
+        console.log("Setup cancelled.");
+        return;
+      }
+      const agents = await askSetupQuestion(rl, "Install for agents? comma-separated", options.agents.join(","));
+      options.agents = parseAgentList(agents);
+      options.inject = await askSetupYesNo(rl, "Enable prompt context injection?", options.inject);
+      options.syncRules = await askSetupYesNo(rl, "Sync project rules and MCP servers through Ruler?", options.syncRules);
+      options.syncSkills = await askSetupYesNo(rl, "Sync skills through skillshare?", options.syncSkills);
+    } finally {
+      rl.close();
+    }
+  }
+
+  console.log("");
+  console.log("◇ Ready to setup:");
+  for (const line of setupSummaryLines({ cwd, ...options })) console.log(`│  ${line}`);
+  console.log("");
+
+  if (!options.agents.length) throw new Error("No agents selected. Use --agents codex,claude,agy.");
+
+  for (const agent of options.agents) {
+    console.log(`● Setting up ${agent}...`);
+    await install({ agent, inject: options.inject, copy: false });
+  }
+
+  if (options.syncRules) {
+    console.log("● Syncing project rules and MCP servers...");
+    const syncAgents = options.agents.map((agent) => agent === "agy" ? "antigravity" : agent).join(",");
+    const syncArgs = ["--rules", "--agents", syncAgents];
+    if (options.yes) syncArgs.push("--yes");
+    await syncRules({ cwd, rootDir, args: syncArgs });
+  }
+
+  if (options.syncSkills) {
+    console.log("● Syncing skills...");
+    const skillAgents = options.agents.map((agent) => agent === "agy" ? "antigravity" : agent).join(",");
+    const syncArgs = ["--skills", "--agents", skillAgents];
+    if (options.yes) syncArgs.push("--yes");
+    await syncSkills({
+      cwd,
+      args: syncArgs,
+      rebuildSkillEmbeddings: async ({ cwd: skillCwd, sourceDir }) => warmSkillEmbeddings({
+        cwd: skillCwd,
+        dataDir: contextOSDataDir(),
+        allowRemote: !isModelCacheReady(contextOSDataDir()),
+        skills: scanSkills({ cwd: skillCwd, roots: [sourceDir] })
+      })
+    });
+  }
+
+  console.log("");
+  console.log("╭─ ContextOS is ready ───────────────────────────────────────╮");
+  console.log("│ Next: restart/open your agent from this project directory. │");
+  console.log("│ Try: ctx debug -- \"Recheck authen flow\"                  │");
+  console.log("╰───────────────────────────────────────────────────────────╯");
+}
+
 const args = process.argv.slice(2);
 const command = args[0];
 
@@ -412,6 +514,8 @@ try {
       inject: args.includes("--inject") || !args.includes("--quiet"),
       agent: installAgentFromArgs(args)
     });
+  } else if (command === "setup") {
+    await setup({ args: args.slice(1), cwd: process.cwd() });
   } else if (command === "debug") {
     const marker = args.indexOf("--");
     const task = marker >= 0 ? args.slice(marker + 1).join(" ") : args.slice(1).join(" ");
@@ -451,6 +555,15 @@ try {
     } else {
       await syncRules({ cwd: process.cwd(), rootDir, args: args.slice(1) });
     }
+  } else if (command === "ruler" || command === "skillshare") {
+    const passthrough = parsePassthroughArgs(args);
+    const result = runPassthrough(passthrough);
+    if (result.signal) {
+      console.error(`${passthrough.command} terminated by signal ${result.signal}`);
+      process.exitCode = 1;
+    } else {
+      process.exitCode = result.status;
+    }
   } else {
     throw new Error(`Unknown command: ${command}\n\n${usage()}`);
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@minhpnq1807/contextos",
-  "version": "0.5.6",
+  "version": "0.5.8",
   "description": "Task-aware AGENTS.md context injection and compliance reporting for Codex, Claude Code, and Antigravity.",
   "type": "module",
   "bin": {

package/plugins/ctx/lib/passthrough.js

@@ -0,0 +1,50 @@
+import { spawnSync } from "node:child_process";
+
+const SUPPORTED_COMMANDS = new Set(["ruler", "skillshare"]);
+
+export function parsePassthroughArgs(args = []) {
+  const command = args[0];
+  if (!SUPPORTED_COMMANDS.has(command)) {
+    throw new Error(`Unsupported passthrough command: ${command || ""}`);
+  }
+
+  const separator = args.indexOf("--");
+  if (separator < 0) {
+    throw new Error(`Usage: ctx ${command} -- <${command} args>`);
+  }
+
+  return {
+    command,
+    args: args.slice(separator + 1)
+  };
+}
+
+export function runPassthrough({
+  command,
+  args = [],
+  spawn = spawnSync,
+  cwd = process.cwd(),
+  env = process.env
+} = {}) {
+  if (!SUPPORTED_COMMANDS.has(command)) {
+    throw new Error(`Unsupported passthrough command: ${command || ""}`);
+  }
+
+  const result = spawn(command, args, {
+    cwd,
+    env,
+    stdio: "inherit"
+  });
+
+  if (result.error) {
+    const hint = command === "ruler"
+      ? "Install it with `npm install -g @intellectronica/ruler`."
+      : "Install it with `curl -fsSL https://raw.githubusercontent.com/runkids/skillshare/main/install.sh | sh`.";
+    throw new Error(`Failed to run ${command}: ${result.error.message}. ${hint}`);
+  }
+
+  return {
+    status: typeof result.status === "number" ? result.status : 1,
+    signal: result.signal || null
+  };
+}

package/plugins/ctx/lib/setup-wizard.js

@@ -0,0 +1,47 @@
+const DEFAULT_AGENTS = ["codex", "claude", "agy"];
+
+export function parseSetupArgs(args = []) {
+  const agentsFlag = args.indexOf("--agents");
+  const agents = agentsFlag >= 0
+    ? parseAgentList(args[agentsFlag + 1])
+    : DEFAULT_AGENTS;
+
+  return {
+    agents,
+    yes: args.includes("--yes") || args.includes("-y"),
+    quiet: args.includes("--quiet"),
+    inject: !args.includes("--quiet") && !args.includes("--no-inject"),
+    syncRules: !args.includes("--no-rules"),
+    syncSkills: !args.includes("--no-skills")
+  };
+}
+
+export function parseAgentList(value = "") {
+  const agents = String(value || "")
+    .split(",")
+    .map((item) => normalizeSetupAgent(item))
+    .filter(Boolean);
+  return [...new Set(agents)];
+}
+
+export function normalizeSetupAgent(agent) {
+  const normalized = String(agent || "").trim().toLowerCase();
+  if (normalized === "antigravity") return "agy";
+  return normalized;
+}
+
+export function setupSummaryLines({
+  cwd = process.cwd(),
+  agents = DEFAULT_AGENTS,
+  inject = true,
+  syncRules = true,
+  syncSkills = true
+} = {}) {
+  return [
+    `Installation directory: ${cwd}`,
+    `Agents: ${agents.join(", ") || "(none)"}`,
+    `Prompt context injection: ${inject ? "enabled" : "quiet logging only"}`,
+    `Ruler rule/MCP sync: ${syncRules ? "enabled" : "skipped"}`,
+    `skillshare skill sync: ${syncSkills ? "enabled" : "skipped"}`
+  ];
+}