create-academic-research 0.1.2 → 0.1.4

package/README.md

@@ -34,10 +34,10 @@ software engineering, databases, theory, robotics, IR, PL, graphics, and
 adjacent interdisciplinary CS.
 
 The generated repository is agent-neutral. By default the wizard records
-`agent: auto`, lets the `skills` CLI detect the current local agent, and writes
-generic MCP snippets. Use `--agent <name>` only when you want to force a
-specific target recognized by the `skills` CLI, such as `claude-code`,
-`cursor`, `windsurf`, or another supported local loader.
+`agent: universal`, installs one shared project-local `.agents/skills` copy,
+and writes generic MCP snippets. Use `--agent <name>` only when you want to
+force a specific target recognized by the `skills` CLI, such as `claude-code`,
+`codex`, `cursor`, `windsurf`, or another supported local loader.
 
 ## Default Experience
 
@@ -134,8 +134,10 @@ The create wizard can install that project-local package automatically.
 Those skills are portable `SKILL.md` instructions, but they require an
 agent/runtime that can load skills or include the relevant instructions in
 context. They are not automatic capabilities of every raw model API.
-Use `--agent <agent>` for explicit multi-tool setup; reserve `--agent '*'` for
-cases where you intentionally want every local agent loader populated.
+Use `--agent <agent>` for explicit setup, for example `--agent codex` or
+`--agent claude-code`.
+Avoid `--agent auto` for unattended setup: the upstream `skills` CLI may expand
+it to every agent it detects on the machine.
 
 Preset intent:
 
@@ -164,8 +166,8 @@ Releases are tag-driven. Update `package.json` and `package-lock.json`, commit
 the change, create `vX.Y.Z`, and push the tag:
 
 ```bash
-git tag -a v0.1.2 -m "v0.1.2"
-git push origin main v0.1.2
+git tag -a v0.1.4 -m "v0.1.4"
+git push origin main v0.1.4
 ```
 
 Once the GitHub repository is public, the release workflow validates the tag

package/dist/src/capabilities.d.ts

@@ -1,6 +1,6 @@
 import { type Runner } from "./runner.js";
 import { type McpToolCommandKey } from "./stack.js";
-export declare const DEFAULT_AGENT = "auto";
+export declare const DEFAULT_AGENT = "universal";
 export interface CapabilityState {
     agent: string;
     preset: string;

package/dist/src/capabilities.js

@@ -3,7 +3,8 @@ import { join, relative } from "node:path";
 import YAML from "yaml";
 import { defaultRunner } from "./runner.js";
 import { AGENT_STACK, presetMcpServers } from "./stack.js";
-export const DEFAULT_AGENT = "auto";
+export const DEFAULT_AGENT = "universal";
+const AUTO_AGENT = "auto";
 export async function readCapabilities(root) {
     try {
         return readCapabilitiesFile(root);
@@ -293,7 +294,7 @@ async function writeCapabilityProfile(root, state) {
             lines.push(`- \`${name}\` (${status}): ${server?.smoke_test ?? "Smoke-test before use."}`);
         }
     }
-    lines.push("", "## Rules", "", "- Skill installation is project-local by default.", "- Agent target `auto` lets the local skills CLI detect the active agent.", "- MCP enable/disable changes project records; install/uninstall changes external tools.", "- Keep API keys, tokens, cookies, and browser sessions out of git.", "- Cite repository source records, not raw MCP output alone.", "");
+    lines.push("", "## Rules", "", "- Skill installation is project-local by default.", "- Agent target `universal` installs one shared project-local `.agents/skills` copy.", "- MCP enable/disable changes project records; install/uninstall changes external tools.", "- Keep API keys, tokens, cookies, and browser sessions out of git.", "- Cite repository source records, not raw MCP output alone.", "");
     await writeFile(join(root, "docs/agent/capability-profile.md"), lines.join("\n"), "utf8");
 }
 async function appendCapabilityLog(root, state) {
@@ -307,7 +308,7 @@ function dedupe(values) {
 }
 function renderSkillCommand(command, agent) {
     const normalized = normalizeAgent(agent);
-    const agentFlag = normalized === DEFAULT_AGENT ? "" : `--agent '${normalized}'`;
+    const agentFlag = normalized === AUTO_AGENT ? "" : `--agent '${normalized}'`;
     return command.replaceAll("{agent_flag}", agentFlag).replaceAll("{agent}", normalized);
 }
 async function readCapabilitiesFile(root) {
@@ -402,7 +403,7 @@ function normalizeAgent(agent) {
 }
 function mcpSnippetFileName(agent) {
     const normalized = normalizeAgent(agent);
-    return normalized === DEFAULT_AGENT ? "mcp.json" : `${normalized}-mcp.json`;
+    return normalized === DEFAULT_AGENT || normalized === AUTO_AGENT ? "mcp.json" : `${normalized}-mcp.json`;
 }
 async function removeInactiveMcpSnippets(outputDir, activeFile) {
     const entries = await readdir(outputDir);

package/dist/src/cli.d.ts

@@ -1,3 +1,4 @@
 type CliMode = "create" | "lifecycle";
 export declare function main(argv?: string[], mode?: CliMode): Promise<number>;
+export declare function formatInteractiveCreateGuide(): string;
 export {};

package/dist/src/cli.js

@@ -16,8 +16,8 @@ const MCP_FLAGS = flagSchema(["help"], ["root", "agent"]);
 export async function main(argv = process.argv.slice(2), mode = "create") {
     try {
         if (mode === "create")
-            return createMain(argv);
-        return lifecycleMain(argv);
+            return await createMain(argv);
+        return await lifecycleMain(argv);
     }
     catch (error) {
         console.error(error instanceof Error ? error.message : String(error));
@@ -61,7 +61,7 @@ async function createMain(argv) {
         : undefined;
     const installMcpToolsLock = flagBool(parsed.flags, "install-mcp-tools") ? true : undefined;
     const answers = interactive
-        ? await askCreateOptions(defaults, {
+        ? await askInteractiveCreateOptions(defaults, {
             installSkills: installSkillsLock,
             installMcpTools: installMcpToolsLock
         })
@@ -83,6 +83,10 @@ async function createMain(argv) {
     console.log("Next: cd into the project and run `npx academic-research doctor`.");
     return 0;
 }
+async function askInteractiveCreateOptions(defaults, locks) {
+    console.log(formatInteractiveCreateGuide());
+    return askCreateOptions(defaults, locks);
+}
 async function lifecycleMain(argv) {
     const command = argv[0] ?? "help";
     if (command === "--help" || command === "-h") {
@@ -388,6 +392,27 @@ function mcpInstallMode(installCommand, runtimeCommand) {
         return installCommand;
     return runtimeCommand ? "runtime-only" : "manual";
 }
+export function formatInteractiveCreateGuide() {
+    const presetLines = Object.entries(AGENT_STACK.presets).map(([name, preset]) => `  ${name.padEnd(10)} ${preset.description}`);
+    return [
+        "Setup choices:",
+        "",
+        "Capability presets:",
+        ...presetLines,
+        "",
+        "Agent target:",
+        "  universal  Default. Installs one shared project-local .agents/skills copy.",
+        "  codex      Codex-specific project-local skill install.",
+        "  auto       Lets the upstream skills CLI detect agents; may install to multiple agent loaders.",
+        "",
+        "Skill and MCP behavior:",
+        "  Skills are copied into the project, not installed globally.",
+        "  MCP records are written into configs/capabilities.yaml and docs/agent/generated/.",
+        "  MCP installers are optional and run only finite installer commands.",
+        "  runtime-only MCP servers are configured for the MCP client but have no install step.",
+        ""
+    ].join("\n");
+}
 function printCreateHelp() {
     console.log([
         "Usage: create-academic-research <project-name> [options]",
@@ -401,7 +426,7 @@ function printCreateHelp() {
         "  --package <name>         Python package name. Default: normalized project name.",
         "  --preset <name>           Capability preset: minimal, default, enhanced, literature, writing, full.",
         "  --profile <name>          Project profile metadata. Default: academic-general.",
-        "  --agent <name>            Agent target. Default: auto-detect.",
+        "  --agent <name>            Agent target. Default: universal.",
         "  --install-skills          Install project-local skills without prompting.",
         "  --no-install-skills       Skip project-local skill installation.",
         "  --install-mcp-tools       Run finite external MCP install commands after creation.",

package/dist/src/project.js

@@ -92,7 +92,7 @@ export async function createProject(options) {
     const preset = options.preset ?? "default";
     const agent = options.agent ?? DEFAULT_AGENT;
     if (!AGENT_STACK.presets[preset]) {
-        throw new Error(`unknown capability preset: ${preset}`);
+        throw new Error(`unknown capability preset: ${preset}. Expected one of: ${Object.keys(AGENT_STACK.presets).join(", ")}`);
     }
     await mkdir(dirname(target), { recursive: true });
     await copyDirectory(templateRoot, target);
@@ -205,7 +205,7 @@ async function writeGeneratedPackageJson(root, { slug }) {
     const path = join(root, "package.json");
     const data = await readJson(path);
     const existingSpec = data.devDependencies?.["create-academic-research"];
-    const packageSpec = process.env.CREATE_ACADEMIC_RESEARCH_PACKAGE_SPEC ?? existingSpec ?? "^0.1.2";
+    const packageSpec = process.env.CREATE_ACADEMIC_RESEARCH_PACKAGE_SPEC ?? existingSpec ?? "0.1.4";
     data.name = slug;
     data.devDependencies = {
         ...(data.devDependencies ?? {}),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-academic-research",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "Create and manage agent-ready academic research repositories.",
   "type": "module",
   "license": "MIT",

package/template/README.md

@@ -16,7 +16,8 @@ actual discipline. The companion `academic-research-skills` package gives
 first-class support to computer science research while keeping the repository
 structure useful for broader academic work.
 
-The repository is agent-neutral. Capability state uses `agent: auto` unless a
+The repository is agent-neutral. Capability state uses `agent: universal` by
+default, which installs one shared project-local `.agents/skills` copy unless a
 specific agent target is selected with `--agent`.
 
 ## Quickstart

package/template/configs/capabilities.yaml

@@ -1,4 +1,4 @@
-agent: auto
+agent: universal
 preset: default
 scope: project-local
 mcp_servers: []

package/template/docs/agent/capability-profile.md

@@ -1,6 +1,6 @@
 # Agent Capability Profile
 
-- Agent target: `auto`
+- Agent target: `universal`
 - Scope: `project-local`
 
 This file is written during project creation.

package/template/package.json

@@ -12,6 +12,6 @@
     "mcp:doctor": "academic-research mcp doctor"
   },
   "devDependencies": {
-    "create-academic-research": "^0.1.2"
+    "create-academic-research": "0.1.4"
   }
 }