@minhpnq1807/contextos 0.5.7 → 0.5.8

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # 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.

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
+```
+
+`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 Codex after installing, then use Codex normally. ContextOS runs through Codex hooks and the `ctx-mcp` MCP server.
+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
 ```
@@ -323,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. |

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";
 
@@ -25,6 +27,7 @@ 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, "..");
@@ -42,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
@@ -394,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];
 
@@ -415,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(" ");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@minhpnq1807/contextos",
-  "version": "0.5.7",
+  "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/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"}`
+  ];
+}