create-academic-research 0.1.11 → 0.1.13

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,8 +1,19 @@
1
1
  # Create Academic Research
2
2
 
3
+ [![npm](https://img.shields.io/npm/v/create-academic-research)](https://www.npmjs.com/package/create-academic-research)
4
+ [![Validate](https://github.com/VincenzoImp/create-academic-research/actions/workflows/validate.yml/badge.svg)](https://github.com/VincenzoImp/create-academic-research/actions/workflows/validate.yml)
5
+ [![Release](https://github.com/VincenzoImp/create-academic-research/actions/workflows/release.yml/badge.svg)](https://github.com/VincenzoImp/create-academic-research/actions/workflows/release.yml)
6
+ [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
7
+
3
8
  Create agent-ready academic research repositories with one command.
4
9
 
5
- From the npm registry:
10
+ `create-academic-research` scaffolds a serious research workspace: source
11
+ ledgers, SOTA files, citation audit tables, experiment records, reproducibility
12
+ docs, durable wiki/log memory, project-local skills, and MCP setup for scholarly
13
+ search. The template is discipline-general and especially strong for computer
14
+ science research.
15
+
16
+ ## Quickstart
6
17
 
7
18
  ```bash
8
19
  npm create academic-research@latest my-project
@@ -23,9 +34,16 @@ From GitHub:
23
34
  npx --yes github:VincenzoImp/create-academic-research my-project
24
35
  ```
25
36
 
26
- The generator creates a complete research repository, personalizes the project
27
- name and Python package, configures project-local skills, writes MCP records,
28
- and prepares a durable wiki/log structure for agentic academic work.
37
+ ## What It Creates
38
+
39
+ | Area | Generated Support |
40
+ |---|---|
41
+ | Sources | PDFs, derived Markdown, metadata, BibTeX, conversion ledger, source ledger. |
42
+ | Literature Review | Search strategy, screening decisions, literature matrix, SOTA synthesis, gaps, PRISMA flow. |
43
+ | Agent Memory | `AGENTS.md`, capability profile, MCP setup docs, generated MCP snippets, wiki index/log/templates. |
44
+ | Reproducibility | Python package scaffold, tests, experiment registry, output folders, artifact checklist. |
45
+ | Skills | Project-local installation flow for `VincenzoImp/academic-research-skills`. |
46
+ | MCP | Conservative default records for scholarly discovery plus documented optional integrations. |
29
47
 
30
48
  The wizard is discipline-general: it creates a clean structure for academic
31
49
  research projects in any field. Its companion skill stack gives first-class
@@ -37,9 +55,18 @@ The generated repository is agent-neutral. By default the wizard records
37
55
  `agent: universal`, installs one shared project-local `.agents/skills` copy,
38
56
  and writes generic MCP snippets. Use `--agent <id>` only when you want to force
39
57
  a specific target recognized by the `skills` CLI. Run
40
- `npx academic-research agents list` inside a generated project to see every
58
+ `npm run agents:list` inside a generated project to see every
41
59
  supported target and alias.
42
60
 
61
+ ## When To Use It
62
+
63
+ Use this when starting or cleaning up an academic research project that needs
64
+ evidence tracking, literature-review discipline, repeatable experiments, paper
65
+ writing support, or LLM-agent collaboration. It is not a paper generator and it
66
+ does not replace methodological judgment; it gives the repository enough
67
+ structure for serious research work to compound instead of scattering across
68
+ chat history, notebooks, PDFs, and ad hoc folders.
69
+
43
70
  ## Default Experience
44
71
 
45
72
  By default, the wizard:
@@ -86,35 +113,38 @@ npx create-academic-research@latest my-project --yes --no-install-skills
86
113
  Inside a generated project:
87
114
 
88
115
  ```bash
89
- npx academic-research doctor
90
- npx academic-research setup
91
- npx academic-research rename --title "New Title" --slug new-title --package new_title
92
- npx academic-research agents list
93
- npx academic-research skills presets
94
- npx academic-research skills install --preset default
95
- npx academic-research skills install --preset enhanced
96
- npx academic-research skills install source-ingestion sota-literature-review
97
- npx academic-research skills list
98
- npx academic-research skills status
99
- npx academic-research skills remove source-ingestion
100
- npx academic-research skills uninstall source-ingestion
101
- npx academic-research skills update
102
- npx academic-research mcp list
103
- npx academic-research mcp enabled
104
- npx academic-research mcp available
105
- npx academic-research mcp commands arxiv
106
- npx academic-research mcp env openalex semantic-scholar zotero
107
- npx academic-research mcp env --dotenv --all > .env.example
108
- npx academic-research mcp env --write .env.example --all
109
- npx academic-research mcp enable arxiv dblp
110
- npx academic-research mcp disable arxiv
111
- npx academic-research mcp install arxiv
112
- npx academic-research mcp uninstall arxiv
113
- npx academic-research mcp smoke --env-file .env.local
114
- npx academic-research mcp doctor --env-file .env.local
115
- npx academic-research mcp probe arxiv --timeout-ms 5000
116
+ npm run doctor
117
+ npm run setup
118
+ npm run rename -- --title "New Title" --slug new-title --package new_title
119
+ npm run agents:list
120
+ npm run skills:presets
121
+ npm run skills:install
122
+ npm run skills:install -- --preset enhanced
123
+ npm run skills:install -- source-ingestion sota-literature-review
124
+ npm run skills:list
125
+ npm run skills:status
126
+ npm run skills:remove -- source-ingestion
127
+ npm run skills:uninstall -- source-ingestion
128
+ npm run skills:update
129
+ npm run mcp:list
130
+ npm run mcp:enabled
131
+ npm run mcp:available
132
+ npm run mcp:commands -- arxiv
133
+ npm run mcp:env -- openalex semantic-scholar zotero
134
+ npm run mcp:env -- --dotenv --all > .env.example
135
+ npm run mcp:dotenv
136
+ npm run mcp:enable -- arxiv dblp
137
+ npm run mcp:disable -- arxiv
138
+ npm run mcp:install -- arxiv
139
+ npm run mcp:uninstall -- arxiv
140
+ npm run mcp:smoke -- --env-file .env.local
141
+ npm run mcp:doctor -- --env-file .env.local
142
+ npm run mcp:probe -- arxiv --timeout-ms 5000
116
143
  ```
117
144
 
145
+ For direct one-off invocation without the generated package scripts, use
146
+ `npx --yes --package create-academic-research@latest academic-research <command>`.
147
+
118
148
  ## Command Model
119
149
 
120
150
  `academic-research setup` is a non-destructive onboarding status command. It
@@ -162,7 +192,7 @@ Those skills are portable `SKILL.md` instructions, but they require an
162
192
  agent/runtime that can load skills or include the relevant instructions in
163
193
  context. They are not automatic capabilities of every raw model API.
164
194
  Use `--agent <id>` for explicit setup with any id from
165
- `academic-research agents list`. The shorthand `--agent claude` is normalized
195
+ `npm run agents:list`. The shorthand `--agent claude` is normalized
166
196
  to the supported `claude-code` target.
167
197
  Avoid `--agent auto` for unattended setup: the upstream `skills` CLI may expand
168
198
  it to every agent it detects on the machine.
@@ -181,9 +211,9 @@ Preset intent:
181
211
  MCP defaults are intentionally conservative. Semantic Scholar, OpenAlex,
182
212
  Zotero, Overleaf, Crossref, and fallback aggregators are useful, but they need
183
213
  API keys, local apps, manual setup, or source-policy review. Enable them with
184
- `npx academic-research mcp enable <server>` after reading
185
- `docs/agent/mcp-setup.md`, use `npx academic-research mcp env <server>` to see
186
- runtime prerequisites, then run `npx academic-research mcp doctor`.
214
+ `npm run mcp:enable -- <server>` after reading
215
+ `docs/agent/mcp-setup.md`, use `npm run mcp:env -- <server>` to see runtime
216
+ prerequisites, then run `npm run mcp:doctor`.
187
217
 
188
218
  The MCP catalog distinguishes local runtime adapters from hosted endpoints and
189
219
  manual integrations. arXiv and DBLP are low-friction local `uvx` runtimes.
@@ -198,8 +228,8 @@ until a project explicitly needs them.
198
228
 
199
229
  Generated projects include a committed `.env.example` with empty MCP variables
200
230
  and ignore filled `.env` or `.env.local` files. Regenerate the example with
201
- `mcp env --write .env.example --all`. `mcp doctor`, `mcp smoke`, and
202
- `mcp probe` check the current process environment unless you explicitly pass
231
+ `npm run mcp:dotenv`. `mcp doctor`, `mcp smoke`, and `mcp probe` check the
232
+ current process environment unless you explicitly pass
203
233
  `--env-file .env.local`.
204
234
 
205
235
  Generated MCP snippets are project documentation and client-ready config, not
@@ -229,8 +259,8 @@ Releases are tag-driven. Update `package.json` and `package-lock.json`, commit
229
259
  the change, create `vX.Y.Z`, and push the tag:
230
260
 
231
261
  ```bash
232
- git tag -a v0.1.11 -m "v0.1.11"
233
- git push origin main v0.1.11
262
+ git tag -a vX.Y.Z -m "vX.Y.Z"
263
+ git push origin main vX.Y.Z
234
264
  ```
235
265
 
236
266
  Once the GitHub repository is public, the release workflow validates the tag
@@ -79,7 +79,7 @@ export function assertKnownAgentTarget(agent) {
79
79
  throw new Error([
80
80
  `unknown agent target: ${value}`,
81
81
  `Use ${DEFAULT_AGENT}, ${AUTO_AGENT}, or one supported skills.sh agent id.`,
82
- "List targets with: npx -p create-academic-research academic-research agents list",
82
+ "List targets with: npx --yes --package create-academic-research@latest academic-research agents list",
83
83
  `Supported ids: ${specificAgentTargets().join(", ")}`,
84
84
  `Aliases: ${formatAgentAliasesInline()}`
85
85
  ].join("\n"));
@@ -331,12 +331,12 @@ async function writeCapabilityProfile(root, state) {
331
331
  "",
332
332
  "## Skills",
333
333
  "",
334
- `- Install with: \`academic-research skills install --preset ${state.preset ?? "default"}\``,
335
- "- Install selected skills with: `academic-research skills install <skill-id> [...]`",
336
- "- List installed with: `academic-research skills list`",
337
- "- List presets with: `academic-research skills presets`",
338
- "- Remove with: `academic-research skills remove <skill>`",
339
- "- Update with: `academic-research skills update`",
334
+ `- Install with: \`npm run skills:install -- --preset ${state.preset ?? "default"}\``,
335
+ "- Install selected skills with: `npm run skills:install -- <skill-id> [...]`",
336
+ "- List installed with: `npm run skills:list`",
337
+ "- List presets with: `npm run skills:presets`",
338
+ "- Remove with: `npm run skills:remove -- <skill>`",
339
+ "- Update with: `npm run skills:update`",
340
340
  "",
341
341
  "## MCP Servers",
342
342
  ""
@@ -383,7 +383,7 @@ async function writeMcpSetup(root, state) {
383
383
  lines.push(`- \`${name}\` (${status}, ${server.readiness}, ${server.priority}): ${server.source_need}`, ` - Source: \`${server.source}\``, ` - Execution mode: \`${server.execution_mode}\``, ...(server.hosted_url ? [` - Hosted endpoint: <${server.hosted_url}>`] : []), ...server.setup_commands.map((command) => ` - Setup command: \`${command}\``));
384
384
  appendMcpPrerequisiteLines(lines, server.required_env, server.recommended_env, server.local_service);
385
385
  }
386
- lines.push("", "## Operating Rules", "", "- Use `.env.example` as a committed reference and put filled secrets in `.env.local`, your shell, or your MCP client secret store.", "- Print a dotenv-style reference with `npx academic-research mcp env --dotenv --all`.", "- Regenerate a dotenv-style reference with `npx academic-research mcp env --write .env.example --all`.", "- Pass `--env-file .env.local` to `mcp doctor`, `mcp smoke`, or `mcp probe` when you want the CLI to read explicit local secrets.", "- Keep secrets in your shell, MCP client secret store, or local untracked files; do not commit tokens or API keys.", "- Prefer the smallest enabled MCP set that covers the current research question.", "- Treat MCP output as retrieval metadata. Promote claims into repository source records only after source ingestion and citation audit.", "- Run `npx academic-research mcp doctor` after changing MCP records or environment variables.", "- Run `npx academic-research mcp probe <server>` only when you intentionally want to start selected MCP server processes.", "");
386
+ lines.push("", "## Operating Rules", "", "- Use `.env.example` as a committed reference and put filled secrets in `.env.local`, your shell, or your MCP client secret store.", "- Print a dotenv-style reference with `npm run mcp:env -- --dotenv --all`.", "- Regenerate a dotenv-style reference with `npm run mcp:dotenv`.", "- Pass `--env-file .env.local` to `mcp doctor`, `mcp smoke`, or `mcp probe` when you want the CLI to read explicit local secrets.", "- Keep secrets in your shell, MCP client secret store, or local untracked files; do not commit tokens or API keys.", "- Prefer the smallest enabled MCP set that covers the current research question.", "- Treat MCP output as retrieval metadata. Promote claims into repository source records only after source ingestion and citation audit.", "- Run `npm run mcp:doctor` after changing MCP records or environment variables.", "- Run `npm run mcp:probe -- <server>` only when you intentionally want to start selected MCP server processes.", "");
387
387
  await mkdir(join(root, "docs/agent"), { recursive: true });
388
388
  await writeFile(join(root, "docs/agent/mcp-setup.md"), lines.join("\n"), "utf8");
389
389
  }
package/dist/src/cli.js CHANGED
@@ -94,7 +94,7 @@ async function createMain(argv) {
94
94
  await installMcpTools(result.root, presetMcpServers(answers.preset));
95
95
  }
96
96
  console.log(`Created ${result.slug} at ${result.root}`);
97
- console.log("Next: cd into the project and run `npx academic-research doctor`.");
97
+ console.log("Next: cd into the project and run `npm run doctor`.");
98
98
  return 0;
99
99
  }
100
100
  async function askInteractiveCreateOptions(defaults, locks) {
@@ -167,14 +167,14 @@ async function setupCommand(argv) {
167
167
  }
168
168
  console.log("");
169
169
  console.log("Next Commands");
170
- console.log(`academic-research skills install --preset ${state.preset}`);
171
- console.log("academic-research skills status");
172
- console.log("academic-research mcp list");
173
- console.log("academic-research mcp env");
174
- console.log("academic-research mcp env --write .env.example --all");
175
- console.log("academic-research mcp smoke");
176
- console.log("academic-research mcp probe arxiv");
177
- console.log("academic-research doctor");
170
+ console.log(`npm run skills:install -- --preset ${state.preset}`);
171
+ console.log("npm run skills:status");
172
+ console.log("npm run mcp:list");
173
+ console.log("npm run mcp:env");
174
+ console.log("npm run mcp:dotenv");
175
+ console.log("npm run mcp:smoke");
176
+ console.log("npm run mcp:probe -- arxiv");
177
+ console.log("npm run doctor");
178
178
  return project.ok ? 0 : 1;
179
179
  }
180
180
  async function renameCommand(argv) {
@@ -579,10 +579,10 @@ export function formatInteractiveCreateGuide() {
579
579
  " default enables only low-friction arXiv; credentialed/local services are opt-in.",
580
580
  " MCP installers are optional and run only finite installer commands.",
581
581
  " MCP execution modes are explicit: uvx-runtime, npx-runtime, local-service, manual, or fallback.",
582
- " Use `academic-research mcp env <server>` to inspect env vars and local prerequisites.",
583
- " Use `academic-research mcp env --dotenv --all` to print a committed env example.",
584
- " Use `academic-research mcp env --write .env.example --all` to regenerate a committed env example.",
585
- " Use `academic-research mcp doctor --env-file .env.local` to check explicit local secrets.",
582
+ " Use `npm run mcp:env -- <server>` to inspect env vars and local prerequisites.",
583
+ " Use `npm run mcp:env -- --dotenv --all` to print a committed env example.",
584
+ " Use `npm run mcp:dotenv` to regenerate a committed env example.",
585
+ " Use `npm run mcp:doctor -- --env-file .env.local` to check explicit local secrets.",
586
586
  ""
587
587
  ].join("\n");
588
588
  }
@@ -223,12 +223,54 @@ async function writeGeneratedPackageJson(root, { slug, preserveExistingSpec = fa
223
223
  (preserveExistingSpec ? existingSpec : undefined) ??
224
224
  await currentPackageVersion();
225
225
  data.name = slug;
226
+ data.scripts = {
227
+ ...(data.scripts ?? {}),
228
+ ...generatedLifecycleScripts(packageSpec)
229
+ };
226
230
  data.devDependencies = {
227
231
  ...(data.devDependencies ?? {}),
228
232
  "create-academic-research": packageSpec
229
233
  };
230
234
  await writeJson(path, data);
231
235
  }
236
+ function generatedLifecycleScripts(packageSpec) {
237
+ const command = `npm exec --yes --package=${lifecyclePackageSpec(packageSpec)} -- academic-research`;
238
+ return {
239
+ doctor: `${command} doctor`,
240
+ setup: `${command} setup`,
241
+ rename: `${command} rename`,
242
+ "agents:list": `${command} agents list`,
243
+ "skills:install": `${command} skills install`,
244
+ "skills:list": `${command} skills list`,
245
+ "skills:status": `${command} skills status`,
246
+ "skills:presets": `${command} skills presets`,
247
+ "skills:remove": `${command} skills remove`,
248
+ "skills:uninstall": `${command} skills uninstall`,
249
+ "skills:update": `${command} skills update`,
250
+ "mcp:list": `${command} mcp list`,
251
+ "mcp:enabled": `${command} mcp enabled`,
252
+ "mcp:available": `${command} mcp available`,
253
+ "mcp:commands": `${command} mcp commands`,
254
+ "mcp:env": `${command} mcp env`,
255
+ "mcp:dotenv": `${command} mcp env --write .env.example --all`,
256
+ "mcp:enable": `${command} mcp enable`,
257
+ "mcp:disable": `${command} mcp disable`,
258
+ "mcp:install": `${command} mcp install`,
259
+ "mcp:uninstall": `${command} mcp uninstall`,
260
+ "mcp:smoke": `${command} mcp smoke`,
261
+ "mcp:doctor": `${command} mcp doctor`,
262
+ "mcp:probe": `${command} mcp probe`
263
+ };
264
+ }
265
+ function lifecyclePackageSpec(packageSpec) {
266
+ if (packageSpec === "create-academic-research" || packageSpec.startsWith("create-academic-research@")) {
267
+ return packageSpec;
268
+ }
269
+ if (/^(file:|github:|git[+:]|https?:)/.test(packageSpec) || packageSpec.includes("/")) {
270
+ return packageSpec;
271
+ }
272
+ return `create-academic-research@${packageSpec}`;
273
+ }
232
274
  async function writeGeneratedGitignore(root) {
233
275
  const source = join(root, "_gitignore");
234
276
  if (await exists(source)) {
package/package.json CHANGED
@@ -1,17 +1,24 @@
1
1
  {
2
2
  "name": "create-academic-research",
3
- "version": "0.1.11",
4
- "description": "Create and manage agent-ready academic research repositories.",
3
+ "version": "0.1.13",
4
+ "description": "Scaffold agent-ready academic research repositories with SOTA, source ledgers, wiki memory, MCP setup, and project-local skills.",
5
5
  "type": "module",
6
6
  "license": "MIT",
7
7
  "author": "Vincenzo Imperati",
8
8
  "keywords": [
9
9
  "academic-research",
10
+ "academic-writing",
11
+ "arxiv",
12
+ "citation-management",
10
13
  "research-project",
14
+ "research-scaffold",
11
15
  "agent-skills",
16
+ "llm-agents",
12
17
  "mcp",
13
18
  "literature-review",
14
- "reproducibility"
19
+ "open-science",
20
+ "reproducibility",
21
+ "sota"
15
22
  ],
16
23
  "repository": {
17
24
  "type": "git",
@@ -30,7 +30,7 @@ python3.11 -m venv .venv
30
30
  source .venv/bin/activate
31
31
  python -m pip install --upgrade pip
32
32
  python -m pip install -e ".[dev]"
33
- npx academic-research doctor
33
+ npm run doctor
34
34
  ```
35
35
 
36
36
  ## Core Folders
@@ -53,23 +53,23 @@ npx academic-research doctor
53
53
  Project-local skills and MCP records are managed with:
54
54
 
55
55
  ```bash
56
- npx academic-research skills presets
57
- npx academic-research agents list
58
- npx academic-research skills install --preset default
59
- npx academic-research skills install --preset enhanced
60
- npx academic-research skills install source-ingestion sota-literature-review
61
- npx academic-research skills list
62
- npx academic-research skills status
63
- npx academic-research setup
64
- npx academic-research mcp env --write .env.example --all
65
- npx academic-research mcp list
66
- npx academic-research mcp env openalex semantic-scholar zotero
67
- npx academic-research mcp enable arxiv dblp
68
- npx academic-research mcp commands arxiv
69
- npx academic-research mcp install arxiv
70
- npx academic-research mcp smoke --env-file .env.local
71
- npx academic-research mcp doctor --env-file .env.local
72
- npx academic-research mcp probe arxiv --timeout-ms 5000
56
+ npm run skills:presets
57
+ npm run agents:list
58
+ npm run skills:install
59
+ npm run skills:install -- --preset enhanced
60
+ npm run skills:install -- source-ingestion sota-literature-review
61
+ npm run skills:list
62
+ npm run skills:status
63
+ npm run setup
64
+ npm run mcp:dotenv
65
+ npm run mcp:list
66
+ npm run mcp:env -- openalex semantic-scholar zotero
67
+ npm run mcp:enable -- arxiv dblp
68
+ npm run mcp:commands -- arxiv
69
+ npm run mcp:install -- arxiv
70
+ npm run mcp:smoke -- --env-file .env.local
71
+ npm run mcp:doctor -- --env-file .env.local
72
+ npm run mcp:probe -- arxiv --timeout-ms 5000
73
73
  ```
74
74
 
75
75
  `skills list` reports installed project-local skills. `skills presets` reports
@@ -81,10 +81,10 @@ commands; runtime-only `uvx`/`npx` MCP servers may have no install step and are
81
81
  started later by the MCP client.
82
82
 
83
83
  `.env.example` is the committed MCP environment reference. Regenerate it with
84
- `mcp env --write .env.example --all`. Copy it to `.env.local`, your shell
85
- profile, or your MCP client secret store when secrets are needed. Filled `.env`
86
- files are ignored by git. `mcp doctor` checks the current process environment
87
- unless you explicitly pass `--env-file .env.local`.
84
+ `npm run mcp:dotenv`. Copy it to `.env.local`, your shell profile, or your MCP
85
+ client secret store when secrets are needed. Filled `.env` files are ignored by
86
+ git. `mcp doctor` checks the current process environment unless you explicitly
87
+ pass `--env-file .env.local`.
88
88
 
89
89
  `setup` prints the current project capability state, installed skill counts,
90
90
  enabled MCP records, and the next onboarding commands without changing files.
@@ -19,7 +19,7 @@ store.
19
19
  Regenerate the committed reference from the current MCP catalog with:
20
20
 
21
21
  ```bash
22
- npx academic-research mcp env --write .env.example --all
22
+ npm run mcp:dotenv
23
23
  ```
24
24
 
25
25
  Create a private local file when needed:
@@ -33,9 +33,9 @@ Do not commit filled `.env`, `.env.local`, tokens, cookies, or browser sessions.
33
33
  environment unless you explicitly pass `--env-file .env.local`.
34
34
 
35
35
  ```bash
36
- npx academic-research mcp doctor --env-file .env.local
37
- npx academic-research mcp smoke --env-file .env.local
38
- npx academic-research mcp probe arxiv --timeout-ms 5000
36
+ npm run mcp:doctor -- --env-file .env.local
37
+ npm run mcp:smoke -- --env-file .env.local
38
+ npm run mcp:probe -- arxiv --timeout-ms 5000
39
39
  ```
40
40
 
41
41
  ## Client Notes
@@ -57,10 +57,10 @@ required variables are already exported.
57
57
  ## Workflow
58
58
 
59
59
  1. Enable only the MCP servers needed for the current research task.
60
- 2. Inspect prerequisites with `npx academic-research mcp env <server>`.
60
+ 2. Inspect prerequisites with `npm run mcp:env -- <server>`.
61
61
  3. Put required secrets in the MCP client secret store, shell, or `.env.local`.
62
- 4. Run `npx academic-research mcp smoke --env-file .env.local`.
63
- 5. Run `npx academic-research mcp probe <server>` only when you want to start
62
+ 4. Run `npm run mcp:smoke -- --env-file .env.local`.
63
+ 5. Run `npm run mcp:probe -- <server>` only when you want to start
64
64
  the server and verify a real stdio handshake.
65
65
  6. Load the generated snippet in the MCP client.
66
66
  7. Treat MCP output as retrieval metadata until it is ingested into repository
@@ -5,9 +5,8 @@ and known risks here.
5
5
 
6
6
  Use `.env.example` as the committed environment reference. Put filled values in
7
7
  `.env.local`, the shell, or the MCP client secret store. Regenerate the example
8
- with `npx academic-research mcp env --write .env.example --all`.
8
+ with `npm run mcp:dotenv`.
9
9
 
10
- Use `npx academic-research mcp doctor --env-file .env.local` when you want the
11
- CLI to read an explicit local env file. Use `npx academic-research mcp probe
12
- <server>` only when you want to start a selected MCP server and verify a real
13
- stdio handshake.
10
+ Use `npm run mcp:doctor -- --env-file .env.local` when you want the CLI to read
11
+ an explicit local env file. Use `npm run mcp:probe -- <server>` only when you
12
+ want to start a selected MCP server and verify a real stdio handshake.
@@ -6,8 +6,8 @@ Use this path for the first working session in a new research repository.
6
6
 
7
7
  ```bash
8
8
  npm install
9
- npx academic-research doctor
10
- npx academic-research setup
9
+ npm run doctor
10
+ npm run setup
11
11
  ```
12
12
 
13
13
  `doctor` checks required files and structural contracts. `setup` prints the
@@ -19,15 +19,15 @@ commands without changing files.
19
19
  Install the default academic research skill package:
20
20
 
21
21
  ```bash
22
- npx academic-research skills install --preset default
23
- npx academic-research skills status
22
+ npm run skills:install
23
+ npm run skills:status
24
24
  ```
25
25
 
26
26
  Use `enhanced` only when the project also needs complementary development,
27
27
  document, frontend, testing, and conversion skills:
28
28
 
29
29
  ```bash
30
- npx academic-research skills install --preset enhanced
30
+ npm run skills:install -- --preset enhanced
31
31
  ```
32
32
 
33
33
  ## 3. Prepare MCP Environment
@@ -36,18 +36,18 @@ Keep `.env.example` committed and empty of real secrets. Put filled values in
36
36
  `.env.local`, your shell, or your MCP client secret store.
37
37
 
38
38
  ```bash
39
- npx academic-research mcp env --write .env.example --all
39
+ npm run mcp:dotenv
40
40
  cp .env.example .env.local
41
- npx academic-research mcp env openalex semantic-scholar zotero
42
- npx academic-research mcp doctor --env-file .env.local
41
+ npm run mcp:env -- openalex semantic-scholar zotero
42
+ npm run mcp:doctor -- --env-file .env.local
43
43
  ```
44
44
 
45
45
  `mcp smoke` is a non-launching readiness check. `mcp probe` is opt-in and starts
46
46
  MCP processes for a real stdio handshake.
47
47
 
48
48
  ```bash
49
- npx academic-research mcp smoke --env-file .env.local
50
- npx academic-research mcp probe arxiv --timeout-ms 5000
49
+ npm run mcp:smoke -- --env-file .env.local
50
+ npm run mcp:probe -- arxiv --timeout-ms 5000
51
51
  ```
52
52
 
53
53
  ## 4. Start Source Work
@@ -3,20 +3,32 @@
3
3
  "private": true,
4
4
  "type": "module",
5
5
  "scripts": {
6
- "doctor": "academic-research doctor",
7
- "setup": "academic-research setup",
8
- "skills:install": "academic-research skills install --preset default",
9
- "skills:list": "academic-research skills list",
10
- "skills:presets": "academic-research skills presets",
11
- "mcp:list": "academic-research mcp list",
12
- "mcp:commands": "academic-research mcp commands",
13
- "mcp:env": "academic-research mcp env",
14
- "mcp:dotenv": "academic-research mcp env --write .env.example --all",
15
- "mcp:smoke": "academic-research mcp smoke",
16
- "mcp:doctor": "academic-research mcp doctor",
17
- "mcp:probe": "academic-research mcp probe"
6
+ "doctor": "npm exec --yes --package=create-academic-research@latest -- academic-research doctor",
7
+ "setup": "npm exec --yes --package=create-academic-research@latest -- academic-research setup",
8
+ "rename": "npm exec --yes --package=create-academic-research@latest -- academic-research rename",
9
+ "agents:list": "npm exec --yes --package=create-academic-research@latest -- academic-research agents list",
10
+ "skills:install": "npm exec --yes --package=create-academic-research@latest -- academic-research skills install",
11
+ "skills:list": "npm exec --yes --package=create-academic-research@latest -- academic-research skills list",
12
+ "skills:status": "npm exec --yes --package=create-academic-research@latest -- academic-research skills status",
13
+ "skills:presets": "npm exec --yes --package=create-academic-research@latest -- academic-research skills presets",
14
+ "skills:remove": "npm exec --yes --package=create-academic-research@latest -- academic-research skills remove",
15
+ "skills:uninstall": "npm exec --yes --package=create-academic-research@latest -- academic-research skills uninstall",
16
+ "skills:update": "npm exec --yes --package=create-academic-research@latest -- academic-research skills update",
17
+ "mcp:list": "npm exec --yes --package=create-academic-research@latest -- academic-research mcp list",
18
+ "mcp:enabled": "npm exec --yes --package=create-academic-research@latest -- academic-research mcp enabled",
19
+ "mcp:available": "npm exec --yes --package=create-academic-research@latest -- academic-research mcp available",
20
+ "mcp:commands": "npm exec --yes --package=create-academic-research@latest -- academic-research mcp commands",
21
+ "mcp:env": "npm exec --yes --package=create-academic-research@latest -- academic-research mcp env",
22
+ "mcp:dotenv": "npm exec --yes --package=create-academic-research@latest -- academic-research mcp env --write .env.example --all",
23
+ "mcp:enable": "npm exec --yes --package=create-academic-research@latest -- academic-research mcp enable",
24
+ "mcp:disable": "npm exec --yes --package=create-academic-research@latest -- academic-research mcp disable",
25
+ "mcp:install": "npm exec --yes --package=create-academic-research@latest -- academic-research mcp install",
26
+ "mcp:uninstall": "npm exec --yes --package=create-academic-research@latest -- academic-research mcp uninstall",
27
+ "mcp:smoke": "npm exec --yes --package=create-academic-research@latest -- academic-research mcp smoke",
28
+ "mcp:doctor": "npm exec --yes --package=create-academic-research@latest -- academic-research mcp doctor",
29
+ "mcp:probe": "npm exec --yes --package=create-academic-research@latest -- academic-research mcp probe"
18
30
  },
19
31
  "devDependencies": {
20
- "create-academic-research": "0.1.11"
32
+ "create-academic-research": "0.1.13"
21
33
  }
22
34
  }