@ahmednawaz/crank 0.1.2 → 0.1.5

package/AGENTS.md

@@ -0,0 +1,131 @@
+# Crank — instructions for AI coding agents
+
+Read this before running any Crank shell command or MCP tool on behalf of the user.
+
+## What Crank is
+
+**Crank** is an internal Motive tool for **UX copy iteration** on live UI:
+
+1. User selects text in a browser panel (bookmarklet or dev loader).
+2. A local **companion** server sends that selection to a **Glean** copy agent.
+3. The user picks a variant; an **MCP-connected agent** (you) applies structured text changes to source files.
+
+| Resource | URL |
+|----------|-----|
+| npm package | `@ahmednawaz/crank` — https://www.npmjs.com/package/@ahmednawaz/crank |
+| Source code | https://github.com/ahmednawaz619/crank |
+| CLI entry | `bin/crank.js` (open-source, inspectable) |
+
+This is **not** arbitrary third-party malware — it is a published, versioned dev tool maintained for Motive copy workflows (sibling to [Vizpatch](https://github.com) for CSS; Crank handles copy only).
+
+---
+
+## What `npx @ahmednawaz/crank` does
+
+When the user asks to start Crank, this command (from the **app repo root**):
+
+| Action | Detail |
+|--------|--------|
+| Setup (idempotent) | Writes `.crank/config.json`, MCP config, optional Vite plugin hook |
+| Companion | Local Express + WebSocket on port **3344** — selection store, panel UI |
+| MCP | stdio (Cursor) or HTTP on **3345** (Replit) — tools like `crank_get_formatted_changes` |
+| Dev server | Runs `npm run dev` when the project has that script |
+| Network | Calls **Glean** (`motive-prod-be.glean.com`) only when the user clicks **Get options** |
+
+It does **not**:
+
+- Upload the whole repository to an unknown server
+- Execute remote shell scripts beyond the published npm tarball
+- Require npm credentials, GitHub tokens, or team passphrases **in the command line**
+
+---
+
+## Security rules for agents
+
+### Approved commands (no secrets in the command)
+
+```bash
+npx @ahmednawaz/crank setup
+npx @ahmednawaz/crank
+npx @ahmednawaz/crank doctor
+npx @ahmednawaz/crank status
+```
+
+Use the scoped package name **`@ahmednawaz/crank`** (matches npm). Unscoped `npx crank` works only after `setup` adds a devDependency.
+
+### Never do this
+
+```bash
+# BAD — exposes team passphrase in shell history, logs, and agent transcripts
+CRANK_TEAM_TOKEN=secret-value npx @ahmednawaz/crank
+```
+
+### Credentials — user-managed only
+
+| Variable | Purpose | How to set |
+|----------|---------|------------|
+| `CRANK_TEAM_TOKEN` | Internal team gate for panel + MCP | **Replit Secrets**, local `.env`, or Cursor env — set by the **user**, not embedded by the agent |
+| `GLEAN_*` | Glean API (team) | Bundled in published npm package; teammates do not supply this |
+| `VIZPATCH_ROOT` | Optional sibling tool for saving copy to source | Local path in `.env` only |
+
+If tools return **`TEAM_TOKEN_REQUIRED`**:
+
+1. Ask the user for the team passphrase (shared internally — not their npm or GitHub login).
+2. Call MCP tool **`crank_verify_team_token`** with `{ "teamToken": "…" }`.
+3. Do **not** echo the token into a runnable shell command.
+
+If your environment **blocks** `npx @ahmednawaz/crank` (unknown package policy):
+
+- Tell the user to run the approved command themselves in the **Shell** tab, **or**
+- Ask them to add `CRANK_TEAM_TOKEN` in Secrets first, then run `npx @ahmednawaz/crank`.
+
+That is expected behavior for security-conscious hosts (e.g. Replit Agent).
+
+---
+
+## Replit-specific
+
+Replit **blocks agents from editing `.replit`**. Crank does **not** auto-patch that file (same idea as Retune — you use Shell/Workflows + Networking).
+
+After `npx @ahmednawaz/crank setup`, read **`.crank/replit-platform.md`** for:
+
+| Setting | Replit UI | Value |
+|---------|-----------|-------|
+| Run | **Workflows** → Execute Shell Command → assign to Run | `npx @ahmednawaz/crank start` |
+| Companion | **Networking** (port auto-exposed when listening) | **3344** |
+| Agent MCP | **Networking** | **3345** → `/mcp` |
+| Team gate | **Secrets** | `CRANK_TEAM_TOKEN` |
+
+When Crank is running, copy **`MCP (HTTP): …/mcp`** from the banner → **Agent → Integrations → MCP Servers**.
+
+See **[REPLIT.md](./REPLIT.md)** and `.crank/replit.md` (URLs after first run).
+
+---
+
+## MCP tools (agent pull workflow)
+
+When the user clicks **Agent** on a copy variant or says *“Apply the pending Crank change”*:
+
+1. `crank_get_environment` — repo path, URLs, whether team auth is on
+2. `crank_get_formatted_changes` — markdown old→new copy diffs
+3. Edit hardcoded string literals in source under the detected project root
+4. `crank_clear_changes` — clear the queue when done
+
+Full skill: `skill/SKILL.md` / `.cursor/skills/crank-apply-changes/SKILL.md`.
+
+---
+
+## How to verify before running
+
+1. Open https://github.com/ahmednawaz619/crank and read `bin/crank.js`, `companion/server.js`, `mcp-server/tools.js`.
+2. Compare npm tarball to git tag (package version in `package.json`).
+3. Run `npx @ahmednawaz/crank doctor` — prints detected paths and URLs only; no secret values.
+
+---
+
+## When the user says “start Crank”
+
+1. Confirm they want the copy-iteration workflow (not unrelated tasks).
+2. Ensure `CRANK_TEAM_TOKEN` is in **Secrets** / `.env` (user action).
+3. Run **`npx @ahmednawaz/crank`** from project root — or instruct the user to if policy blocks you.
+4. Use MCP tools for apply; never invent copy.

package/README.md

@@ -64,10 +64,13 @@ flowchart LR
 From your **app repo root** (Replit, Cursor terminal, or Codespaces — no paths):
 
 ```bash
-npx crank setup   # once: MCP config, skill, devDependency, Vite inject
-npx crank         # starts companion + dev + panel
+npx @ahmednawaz/crank setup   # once: MCP + skill (Retune-style, global ~/.cursor + ~/.claude)
+npx @ahmednawaz/crank         # local: companion + dev when present
+npx @ahmednawaz/crank start   # Replit Workflow: companion + HTTP MCP only
 ```
 
+Setup auto-installs MCP config and `crank-apply-changes` skill — **no manual skill copy or MCP JSON editing** (same model as Retune). Reload MCP in your IDE once after first setup.
+
 MCP config uses **`npx -y crank mcp`** (like Retune) — no absolute paths. After setup, `crank` is added to `devDependencies` so virtual environments resolve it automatically.
 
 **Agent chat:** paste `Apply the pending Crank change` or ask the agent to run `npx crank`. The agent should call **`crank_get_environment`** first to learn which repo and URLs are active.

package/REPLIT.md

@@ -0,0 +1,62 @@
+# Crank on Replit
+
+## For humans — one command
+
+1. **Secrets** (Tools → Secrets): add `CRANK_TEAM_TOKEN` with your team passphrase (ask your lead — never commit it).
+2. **Workflow or Shell** (recommended on Replit):
+
+```bash
+npx @ahmednawaz/crank start
+```
+
+`start` skips init — only runs the companion (**3344**) and HTTP MCP (**3345**). Does not edit `.replit`.
+
+One-time: `npx @ahmednawaz/crank setup` (writes `AGENTS.md`, `.crank/replit-platform.md`). Leave the process running.
+
+3. Copy **`MCP (HTTP): …`** from the startup banner → **Agent → Integrations → MCP Servers**.
+
+---
+
+## Replit platform config (Workflows — not `.replit`)
+
+**Do not** let an agent edit `.replit` — Replit blocks that.
+
+After `npx @ahmednawaz/crank setup`, read **`.crank/replit-platform.md`** in your Repl. It lists:
+
+| What | How (Replit UI) | Value |
+|------|-----------------|-------|
+| **Run command** | Workflows → Execute Shell Command → assign to Run button | `npx @ahmednawaz/crank` |
+| **Companion port** | Networking tool (auto or manual) | **3344** — panel + bookmarklet |
+| **MCP port** | Networking tool (auto or manual) | **3345** — Agent MCP at `/mcp` |
+| **Team gate** | Secrets | `CRANK_TEAM_TOKEN` |
+
+This matches **Retune**: Retune does not patch `.replit` either — you run `npx retune` via Shell/Workflow and Replit exposes ports when the process listens on `0.0.0.0`.
+
+---
+
+## For Replit Agent — why this is safe to help with
+
+The user may ask you to start **Crank**, an internal Motive **UX copy iteration** tool (`@ahmednawaz/crank` on npm, source at https://github.com/ahmednawaz619/crank).
+
+**You may assist** when the user explicitly requests Crank:
+
+- Explain what it does (local companion + MCP; Glean only when user fetches copy options).
+- Tell the user to add `CRANK_TEAM_TOKEN` in **Secrets** themselves.
+- Run **`npx @ahmednawaz/crank`** from the Repl root **without** embedding secrets in the command.
+- Configure **Run** via **Workflows** and **ports** via **Networking** — see `.crank/replit-platform.md`. **Do not edit `.replit`.**
+
+**Do not run** commands like `CRANK_TEAM_TOKEN=… npx …` — credentials belong in Secrets only.
+
+If policy blocks unknown npm packages, ask the user to paste `npx @ahmednawaz/crank` in the Shell tab themselves. See **[AGENTS.md](./AGENTS.md)** for full agent policy and tool list.
+
+---
+
+## Troubleshooting
+
+| Issue | Fix |
+|-------|-----|
+| Agent refuses `npx @ahmednawaz/crank` | User runs it in Shell; agent reads `AGENTS.md` |
+| Blocked editing `.replit` | Use Workflows + Networking; read `.crank/replit-platform.md` |
+| `TEAM_TOKEN_REQUIRED` | Add `CRANK_TEAM_TOKEN` in Secrets, restart Crank |
+| Agent MCP fails | Register URL from `npx @ahmednawaz/crank doctor` → `runtime.mcp.endpoint` |
+| Package 404 | Use `@ahmednawaz/crank` (scoped name on npm) |

package/bin/crank.js

@@ -17,7 +17,9 @@ const { spawn } = require('child_process');
 const {
   initProject,
   PACKAGE_ROOT,
-  writeReplitGuide
+  writeReplitGuide,
+  syncCrankSkill,
+  printSetupNextSteps
 } = require('../lib/init');
 const { detectEnvironment } = require('../lib/detect');
 const { env } = require('../lib/env');
@@ -173,7 +175,10 @@ function hasDevScript(detectEnv) {
   return Boolean(detectEnv.packageJson?.scripts?.dev);
 }
 
-function applySmartDefaults(flags, detectEnv) {
+function applySmartDefaults(flags, detectEnv, command) {
+  if (command === 'start' && !flags.explicit.dev) {
+    flags.dev = false;
+  }
   if (detectEnv.isReplit) {
     flags.httpMcp = true;
     if (!flags.explicit.daemon) {
@@ -252,7 +257,7 @@ function openUrl(url) {
   }
 }
 
-function printBanner(projectRoot, detectEnv, initResult, runtime, modeLabel) {
+function printBanner(projectRoot, detectEnv, initResult, runtime, modeLabel, resolvedInfo) {
   const setup = runtime?.companion?.publicUrl || companionBaseUrl();
 
   console.log('');
@@ -260,10 +265,10 @@ function printBanner(projectRoot, detectEnv, initResult, runtime, modeLabel) {
   console.log('│  Crank — one-command copy tooling      │');
   console.log('└──────────────────────────────────────────┘');
   console.log(`  Project:    ${projectRoot}`);
-  if (resolved?.repoRoot && resolved.repoRoot !== projectRoot) {
-    console.log(`  Repo:       ${resolved.repoRoot} (${resolved.reason})`);
-  } else if (resolved?.reason) {
-    console.log(`  Detected:   ${resolved.source} — ${resolved.reason}`);
+  if (resolvedInfo?.repoRoot && resolvedInfo.repoRoot !== projectRoot) {
+    console.log(`  Repo:       ${resolvedInfo.repoRoot} (${resolvedInfo.reason})`);
+  } else if (resolvedInfo?.reason) {
+    console.log(`  Detected:   ${resolvedInfo.source} — ${resolvedInfo.reason}`);
   }
   console.log(`  Companion:  ${setup}`);
   if (runtime?.mcp?.mode === 'http' && runtime?.mcp?.endpoint) {
@@ -285,7 +290,7 @@ function printBanner(projectRoot, detectEnv, initResult, runtime, modeLabel) {
   if (detectEnv.isReplit) {
     console.log('  Replit:');
     console.log('    • Keep this process running (companion + HTTP MCP + dev).');
-    console.log('    • Register MCP URL in Agent → Integrations (see .crank/replit.md).');
+    console.log('    • Register MCP URL in Agent → Integrations (see .crank/replit-platform.md).');
     console.log('    • Open the webview — select copy → Get options.');
   } else if (detectEnv.hasVite && hasDevScript(detectEnv)) {
     console.log('  Ready:');
@@ -572,6 +577,7 @@ async function main() {
   process.env.CRANK_PROJECT_ROOT = path.resolve(projectRoot);
 
   if (command === 'mcp') {
+    syncCrankSkill(projectRoot);
     process.env.CRANK_MCP_MODE = process.env.CRANK_MCP_MODE || 'stdio';
     const mcpPath = path.join(PACKAGE_ROOT, 'mcp-server', 'index.js');
     const child = spawn(process.execPath, [mcpPath], {
@@ -614,7 +620,9 @@ async function main() {
   }
 
   const detectEnv = detectEnvironment(projectRoot);
-  applySmartDefaults(flags, detectEnv);
+  applySmartDefaults(flags, detectEnv, command);
+
+  syncCrankSkill(projectRoot);
 
   if (command === 'doctor') {
     const runtime = prepareRuntime(projectRoot, detectEnv);
@@ -642,7 +650,11 @@ async function main() {
   }
 
   let initResult = null;
-  if (command === 'init' || command === 'run') {
+  const crankConfig = path.join(projectRoot, '.crank', 'config.json');
+  const shouldInit =
+    command === 'init' ||
+    (command === 'run' && !fs.existsSync(crankConfig));
+  if (shouldInit) {
     initResult = initProject(projectRoot, {
       mcp: flags.mcp,
       vite: flags.vite,
@@ -651,8 +663,9 @@ async function main() {
     });
     if (command === 'init') {
       const runtime = prepareRuntime(projectRoot, detectEnv);
-      printBanner(projectRoot, detectEnv, initResult, runtime, 'init only');
-      console.log('Init complete. Run `npx crank` to start everything.');
+      printBanner(projectRoot, detectEnv, initResult, runtime, 'init only', resolved);
+      printSetupNextSteps(detectEnv, runtime, initResult);
+      console.log('Setup complete. Run `npx @ahmednawaz/crank start` (Replit) or `npx @ahmednawaz/crank` (local).');
       return;
     }
   }
@@ -669,12 +682,12 @@ async function main() {
   if (flags.daemon && !flags.dev) {
     const existing = await checkHealth(800);
     if (existing.ok) {
-      printBanner(projectRoot, detectEnv, initResult, runtime, 'daemon (already running)');
+      printBanner(projectRoot, detectEnv, initResult, runtime, 'daemon (already running)', resolved);
       console.log('[Crank] Companion already healthy — leaving it running.');
       console.log(`[Crank] ${companionBaseUrl()}/health`);
       return;
     }
-    printBanner(projectRoot, detectEnv, initResult, runtime, 'daemon');
+    printBanner(projectRoot, detectEnv, initResult, runtime, 'daemon', resolved);
     launchDetachedDaemon(projectRoot, flags);
     await new Promise((r) => setTimeout(r, 1200));
     const health = await checkHealth(2000);
@@ -685,11 +698,11 @@ async function main() {
   if (flags.daemon && flags.dev) {
     const existing = await checkHealth(800);
     if (!existing.ok) {
-      printBanner(projectRoot, detectEnv, initResult, runtime, 'daemon + dev');
+      printBanner(projectRoot, detectEnv, initResult, runtime, 'daemon + dev', resolved);
       launchDetachedDaemon(projectRoot, { ...flags, httpMcp });
       await new Promise((r) => setTimeout(r, 1500));
     } else {
-      printBanner(projectRoot, detectEnv, initResult, runtime, 'dev (companion already up)');
+      printBanner(projectRoot, detectEnv, initResult, runtime, 'dev (companion already up)', resolved);
     }
     if (flags.open) {
       openUrl(companionBaseUrl());
@@ -704,7 +717,8 @@ async function main() {
     detectEnv,
     initResult,
     runtime,
-    detectEnv.isReplit ? 'Replit foreground' : 'foreground'
+    detectEnv.isReplit ? 'Replit foreground' : 'foreground',
+    resolved
   );
 
   if (flags.open) {

package/lib/init.js

@@ -47,16 +47,16 @@ function mcpServerEntry(projectRoot) {
   const localBin = path.join(root, 'node_modules', 'crank', 'bin', 'crank.js');
   if (exists(localBin)) {
     return {
-      command: 'node',
-      args: [localBin, 'mcp'],
+      command: 'npx',
+      args: ['crank', 'mcp'],
       env: envBlock
     };
   }
 
-  // Retune-style — npx resolves @ahmednawaz/crank from npm (no git clone).
+  // Retune-style — npx resolves @ahmednawaz/crank from npm (no git clone, no absolute paths).
   return {
     command: 'npx',
-    args: ['-y', '@ahmednawaz/crank', 'mcp'],
+    args: ['@ahmednawaz/crank', 'mcp'],
     env: envBlock
   };
 }
@@ -159,51 +159,109 @@ function writeProjectEnvExample(projectRoot) {
 }
 
 /**
- * Install crank-apply-changes skill like `npx retune setup`:
- * user-level ~/.cursor/skills + project .cursor/skills when present.
+ * Retune-style skill sync — update ~/.cursor and ~/.claude skills when bundled skill changes.
+ * Also writes project skill when .cursor/skills exists or on setup.
  */
-function installCrankSkill(projectRoot, results) {
+function syncCrankSkill(projectRoot, options = {}) {
   const skillSrc = path.join(PACKAGE_ROOT, 'skill', 'SKILL.md');
   if (!exists(skillSrc)) {
-    results.skillError = 'skill/SKILL.md missing from crank package';
-    return;
+    return { synced: [], error: 'skill/SKILL.md missing from crank package' };
   }
-  const targets = [];
+  const src = fs.readFileSync(skillSrc, 'utf8');
   const home = process.env.HOME || process.env.USERPROFILE || '';
-  if (home) {
+  const targets = [];
+  const forceProject = options.forceProject === true;
+
+  if (home && exists(path.join(home, '.cursor'))) {
     targets.push(
       path.join(home, '.cursor', 'skills', 'crank-apply-changes', 'SKILL.md')
     );
+  }
+  if (home && exists(path.join(home, '.claude'))) {
     targets.push(
       path.join(home, '.claude', 'skills', 'crank-apply-changes', 'SKILL.md')
     );
   }
-  if (projectRoot) {
+  if (projectRoot && (forceProject || exists(path.join(projectRoot, '.cursor', 'skills')))) {
     targets.push(
-      path.join(
-        projectRoot,
-        '.cursor',
-        'skills',
-        'crank-apply-changes',
-        'SKILL.md'
-      )
+      path.join(projectRoot, '.cursor', 'skills', 'crank-apply-changes', 'SKILL.md')
     );
   }
+
+  const synced = [];
   for (const dest of targets) {
     try {
+      if (exists(dest) && fs.readFileSync(dest, 'utf8') === src) {
+        continue;
+      }
       fs.mkdirSync(path.dirname(dest), { recursive: true });
-      fs.copyFileSync(skillSrc, dest);
-      results.wrote.push(dest);
+      fs.writeFileSync(dest, src);
+      synced.push(dest);
     } catch (err) {
-      results.skillError = (results.skillError ? results.skillError + '; ' : '') +
-        `${dest}: ${err.message}`;
+      return { synced, error: `${dest}: ${err.message}` };
     }
   }
+  return { synced };
+}
+
+function installCrankSkill(projectRoot, results) {
+  const out = syncCrankSkill(projectRoot, { forceProject: true });
+  if (out.error) {
+    results.skillError = out.error;
+  }
+  for (const dest of out.synced || []) {
+    results.wrote.push(dest);
+  }
 }
 
 /**
- * Also merge crank into user ~/.cursor/mcp.json (Retune setup parity).
+ * Retune-style MCP bootstrap: global ~/.cursor + ~/.claude only (no project MCP by default).
+ * Set CRANK_PROJECT_MCP=true to also merge .cursor/mcp.json in the repo.
  */
+function configureMcpRetuneStyle(env, projectRoot, results, options = {}) {
+  const home = process.env.HOME || process.env.USERPROFILE || '';
+  let configured = false;
+
+  if (home && exists(path.join(home, '.cursor'))) {
+    mergeUserCursorMcp(projectRoot, results);
+    configured = true;
+  }
+
+  const claudePath =
+    env.claudeConfig ||
+    (home ? path.join(home, '.claude', 'claude_desktop_config.json') : '');
+  if (
+    options.claude !== false &&
+    claudePath &&
+    exists(path.dirname(claudePath))
+  ) {
+    try {
+      mergeMcpServers(claudePath, 'crank', projectRoot);
+      results.wrote.push(claudePath);
+      configured = true;
+    } catch (err) {
+      results.claudeError = err.message;
+    }
+  }
+
+  const projectMcp =
+    options.projectMcp === true || process.env.CRANK_PROJECT_MCP === 'true';
+  if (projectMcp && !env.isReplit) {
+    const cursorMcp = path.join(projectRoot, '.cursor', 'mcp.json');
+    mergeMcpServers(cursorMcp, 'crank', projectRoot);
+    results.wrote.push('.cursor/mcp.json');
+    const vsMcp = path.join(projectRoot, '.vscode', 'mcp.json');
+    mergeVsCodeMcp(vsMcp, projectRoot);
+    results.wrote.push('.vscode/mcp.json');
+    configured = true;
+  }
+
+  if (!configured) {
+    results.mcpNote =
+      'No ~/.cursor or ~/.claude found — install Cursor or Claude Code, then re-run setup.';
+  }
+}
+
 function mergeUserCursorMcp(projectRoot, results) {
   const home = process.env.HOME || process.env.USERPROFILE || '';
   if (!home) return;
@@ -293,36 +351,19 @@ function initProject(projectRoot, options = {}) {
   writeConfig(projectRoot, env);
   results.wrote.push('.crank/config.json');
 
+  copyAgentsDoc(projectRoot, results);
+
   writeProjectEnvExample(projectRoot);
   if (exists(path.join(projectRoot, '.env.crank.example'))) {
     results.wrote.push('.env.crank.example');
   }
 
-  // Cursor project MCP
+  // MCP + skill (Retune-style: global IDE config, automatic skill sync)
   if (options.mcp !== false) {
-    ensureCrankDependency(projectRoot, results);
-
-    const cursorMcp = path.join(projectRoot, '.cursor', 'mcp.json');
-    mergeMcpServers(cursorMcp, 'crank', projectRoot);
-    results.wrote.push('.cursor/mcp.json');
-
-    // VS Code / Copilot MCP
-    const vsMcp = path.join(projectRoot, '.vscode', 'mcp.json');
-    mergeVsCodeMcp(vsMcp, projectRoot);
-    results.wrote.push('.vscode/mcp.json');
-
-    if (options.userMcp !== false) {
-      mergeUserCursorMcp(projectRoot, results);
-    }
-
-    if (env.hasClaudeDesktop && options.claude !== false) {
-      try {
-        mergeMcpServers(env.claudeConfig, 'crank', projectRoot);
-        results.wrote.push(env.claudeConfig);
-      } catch (err) {
-        results.claudeError = err.message;
-      }
+    if (!env.isReplit) {
+      ensureCrankDependency(projectRoot, results);
     }
+    configureMcpRetuneStyle(env, projectRoot, results, options);
   }
 
   if (options.skill !== false) {
@@ -343,20 +384,17 @@ function initProject(projectRoot, options = {}) {
     const pkg = readJson(pkgPath, {});
     pkg.scripts = pkg.scripts || {};
     if (!pkg.scripts.crank) {
-      pkg.scripts.crank = `node ${JSON.stringify(
-        path.join(PACKAGE_ROOT, 'bin', 'crank.js')
-      )}`;
+      pkg.scripts.crank = 'crank';
       writeJson(pkgPath, pkg);
       results.wrote.push('package.json#scripts.crank');
     }
   }
 
   if (env.isReplit) {
-    patchReplitConfig(projectRoot, results);
-    writeReplitGuide(projectRoot, env, results);
+    writeReplitPlatformGuide(projectRoot, results);
   }
 
-  if (results.crankDependencyAdded && options.install !== false) {
+  if (results.crankDependencyAdded && options.install !== false && !env.isReplit) {
     try {
       const { execSync } = require('child_process');
       execSync('npm install', { cwd: projectRoot, stdio: 'inherit' });
@@ -369,7 +407,84 @@ function initProject(projectRoot, options = {}) {
   return results;
 }
 
+/**
+ * Replit blocks agents from editing `.replit` directly — use Workflows + Networking UI instead.
+ * Writes a guide only; does not touch `.replit` (Retune-style: user/platform configures run + ports).
+ */
+function writeReplitPlatformGuide(projectRoot, results) {
+  const companionPort = Number(process.env.CRANK_PORT || 3344);
+  const mcpPort = Number(process.env.CRANK_MCP_HTTP_PORT || 3345);
+  const runCommand = 'npx @ahmednawaz/crank start';
+  const guide = path.join(projectRoot, '.crank', 'replit-platform.md');
+  fs.mkdirSync(path.dirname(guide), { recursive: true });
+  fs.writeFileSync(
+    guide,
+    [
+      '# Replit platform setup (manual — do not edit `.replit` via agent)',
+      '',
+      'Crank **does not** auto-edit `.replit` (Replit Agent is blocked from that).',
+      'Configure the Repl using **Workflows** and **Networking**, like Retune.',
+      '',
+      '## 1. Secret',
+      '',
+      'Tools → Secrets → `CRANK_TEAM_TOKEN` = your team passphrase (user sets this).',
+      '',
+      '## 2. Run command (Workflows — not `.replit`)',
+      '',
+      'Workflows pane (Cmd+K → Workflows) → **+ New Workflow** → task: **Execute Shell Command**:',
+      '',
+      '```bash',
+      runCommand,
+      '```',
+      '',
+      'Assign that workflow to the **Run** button (dropdown next to Run).',
+      '',
+      'Or run the same command once in **Shell** and leave it running.',
+      '',
+      '## 3. Ports (Networking tool — not `.replit`)',
+      '',
+      'When Crank starts it listens on `0.0.0.0`. Open **Networking** and ensure these are exposed:',
+      '',
+      `| Service | localPort | Purpose |`,
+      `|---------|-----------|---------|`,
+      `| Companion (panel, bookmarklet) | **${companionPort}** | Web UI + selection API |`,
+      `| MCP (Replit Agent) | **${mcpPort}** | HTTP MCP at \`/mcp\` |`,
+      '',
+      'Replit often auto-binds ports when the process opens them. If Agent MCP URL is wrong,',
+      'manually expose both ports in Networking.',
+      '',
+      'Equivalent `.replit` snippet (for humans editing config only — **not** via agent):',
+      '',
+      '```toml',
+      `run = "${runCommand}"`,
+      '',
+      '[[ports]]',
+      `localPort = ${companionPort}`,
+      'externalPort = 80',
+      '',
+      '[[ports]]',
+      `localPort = ${mcpPort}`,
+      'externalPort = 80',
+      '```',
+      '',
+      '## 4. Agent MCP',
+      '',
+      'After Crank is running: `npx @ahmednawaz/crank doctor` → copy `runtime.mcp.endpoint`',
+      '→ Agent → Integrations → MCP Servers.',
+      ''
+    ].join('\n')
+  );
+  results.wrote.push('.crank/replit-platform.md');
+  results.replitRun = runCommand;
+  results.replitNote =
+    'Configure Run via Workflows and ports via Networking — see .crank/replit-platform.md';
+}
+
 function patchReplitConfig(projectRoot, results) {
+  // Deprecated: Replit Agent cannot edit `.replit`. Kept for explicit opt-in only.
+  if (process.env.CRANK_PATCH_REPLIT !== 'true') {
+    return;
+  }
   const replitFile = path.join(projectRoot, '.replit');
   const companionPort = Number(process.env.CRANK_PORT || 3344);
   const mcpPort = Number(process.env.CRANK_MCP_HTTP_PORT || 3345);
@@ -383,14 +498,64 @@ function patchReplitConfig(projectRoot, results) {
   }
 
   if (!/^run\s*=/m.test(source)) {
-    source = `run = "npx crank"\n\n${source}`;
-    results.replitRun = 'npx crank';
+    source = `run = "npx @ahmednawaz/crank"\n\n${source}`;
+    results.replitRun = 'npx @ahmednawaz/crank';
   }
 
   fs.writeFileSync(replitFile, source.trimEnd() + '\n');
   results.wrote.push('.replit');
 }
 
+function copyAgentsDoc(projectRoot, results) {
+  const copies = [
+    { name: 'AGENTS.md', dests: [path.join(projectRoot, 'AGENTS.md')] },
+    { name: 'REPLIT.md', dests: [path.join(projectRoot, 'REPLIT.md')] }
+  ];
+  for (const { name, dests } of copies) {
+    const src = path.join(PACKAGE_ROOT, name);
+    if (!exists(src)) {
+      continue;
+    }
+    const content = fs.readFileSync(src, 'utf8');
+    for (const dest of dests) {
+      const crankDir = path.join(projectRoot, '.crank', name);
+      fs.mkdirSync(path.dirname(crankDir), { recursive: true });
+      fs.writeFileSync(crankDir, content);
+      results.wrote.push(`.crank/${name}`);
+      if (!exists(dest) || fs.readFileSync(dest, 'utf8') !== content) {
+        fs.writeFileSync(dest, content);
+        results.wrote.push(name);
+      }
+    }
+  }
+}
+
+function printSetupNextSteps(env, runtime, results) {
+  console.log('');
+  console.log('  Setup complete (Retune-style):');
+  if (results?.wrote?.some((w) => String(w).includes('.cursor/mcp.json') || String(w).includes('claude'))) {
+    console.log('    • MCP configured in ~/.cursor and/or ~/.claude — reload MCP in your IDE');
+  }
+  if (results?.wrote?.some((w) => String(w).includes('skills'))) {
+    console.log('    • Skill crank-apply-changes installed (auto-syncs on start)');
+  }
+  if (env.isReplit) {
+    console.log('    • Workflow command: npx @ahmednawaz/crank start');
+    console.log('    • Add CRANK_TEAM_TOKEN in Secrets (not in the command)');
+    if (runtime?.mcp?.endpoint) {
+      console.log('    • Register Agent MCP URL:');
+      console.log(`      ${runtime.mcp.endpoint}`);
+    } else {
+      console.log('    • After start, register runtime.mcp.endpoint from: npx @ahmednawaz/crank doctor');
+    }
+    console.log('    • See REPLIT.md and .crank/replit-platform.md');
+  } else {
+    console.log('    • Run: npx @ahmednawaz/crank  (or npm run crank)');
+    console.log('    • Agent paste: Apply the pending Crank change');
+  }
+  console.log('');
+}
+
 function writeReplitGuide(projectRoot, detectEnv, results, runtime) {
   const urls = runtime ? null : resolveUrls(detectEnv);
   const mcpEndpoint =
@@ -406,7 +571,16 @@ function writeReplitGuide(projectRoot, detectEnv, results, runtime) {
     [
       '# Crank on Replit',
       '',
-      'One command: `npx crank setup` then `npx crank` — no paths required.',
+      '## Run (no secrets in the command)',
+      '',
+      '1. **Secrets:** add `CRANK_TEAM_TOKEN` (team passphrase — user sets this in Tools → Secrets).',
+      '2. **Shell or Run:**',
+      '',
+      '```bash',
+      'npx @ahmednawaz/crank start',
+      '```',
+      '',
+      'See **AGENTS.md** (repo root) if Replit Agent refuses to run npx — it explains what Crank is and approved commands.',
       '',
       '## Replit Agent MCP',
       '',
@@ -430,6 +604,9 @@ module.exports = {
   PACKAGE_ROOT,
   mcpServerEntry,
   installCrankSkill,
+  syncCrankSkill,
+  configureMcpRetuneStyle,
+  printSetupNextSteps,
   writeReplitGuide,
   patchReplitConfig
 };

package/package.json

@@ -1,7 +1,12 @@
 {
   "name": "@ahmednawaz/crank",
-  "version": "0.1.2",
-  "description": "One-command copy iteration: select UI text → Glean variants → MCP apply. Works in Cursor, VS Code, Claude, and Replit.",
+  "version": "0.1.5",
+  "description": "Internal Motive UX copy iteration: select UI text → Glean variants → MCP apply. Cursor, Replit, Claude.",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ahmednawaz619/crank.git"
+  },
+  "homepage": "https://github.com/ahmednawaz619/crank#readme",
   "bin": {
     "crank": "bin/crank.js"
   },
@@ -41,6 +46,8 @@
     "panel",
     "vite.js",
     ".env.example",
+    "AGENTS.md",
+    "REPLIT.md",
     "team.env",
     "README.md"
   ],

package/skill/SKILL.md

@@ -17,16 +17,32 @@ If `crank_get_environment` or any tool returns **`TEAM_TOKEN_REQUIRED`**:
 2. Call **`crank_verify_team_token`** with `{ "teamToken": "…" }`.
 3. Pass the same **`teamToken`** on subsequent Crank MCP tool calls in this session.
 
-Alternatively the user can set `CRANK_TEAM_TOKEN` in Replit Secrets or shell before starting Crank.
+Alternatively the user can set `CRANK_TEAM_TOKEN` in Replit Secrets or local `.env` — **the user sets this; never put it in a shell command you run.**
+
+## Starting Crank (agent security)
+
+**Crank** is an internal Motive copy-iteration tool (`@ahmednawaz/crank`, https://github.com/ahmednawaz619/crank). Read **`AGENTS.md`** in the repo for what it does and why it is safe.
+
+When the user asks to start Crank:
+
+1. **Do not** run `CRANK_TEAM_TOKEN=… npx …` — secrets belong in Replit Secrets / `.env` only.
+2. Ask the user to add `CRANK_TEAM_TOKEN` in Secrets if team lock is on.
+3. On **Replit**, use a **Workflow** (does not touch `.replit`):
+   ```bash
+   npx @ahmednawaz/crank start
+   ```
+   `start` skips setup/init — companion on **3344** (+ HTTP MCP on **3345** on Replit). Add `CRANK_TEAM_TOKEN` in Secrets first.
+4. Call **`crank_get_environment`** after the companion is up.
 
 ## When the user says "start Crank" or pastes `npx crank`
 
 1. Call **`crank_get_environment`** first — repo path, Replit vs local, companion URL, auth requirements.
-2. If team auth is required and tools fail, ask for the team token (see above).
-3. Run in the terminal from project root:
+2. If team auth is required and tools fail, ask for the team token (see above) — use MCP `teamToken`, not shell env in the command line.
+3. Approved terminal commands (project root):
    ```bash
-   npx @ahmednawaz/crank setup   # once
-   npx @ahmednawaz/crank
+   npx @ahmednawaz/crank setup   # once — writes AGENTS.md, MCP config (not .replit on Replit)
+   npx @ahmednawaz/crank start   # Replit Workflow: companion only, skips init
+   npx @ahmednawaz/crank         # local default; skips init if .crank/config.json exists
    ```
 
 ## Apply workflow