fix(init): generated instructions work without a global graft install (#61)

[Frankie-Xu]

Summary

• graft init does not install a global graft binary, but AGENTS.md / GEMINI.md / SKILL.md (and the other host copies of the same body) told agents to run bare graft ask. The first command then failed with command-not-found.
• Chose scheme 2 (a fallback note) over rewriting every example as npx @nanonets/graft …: smaller diff, and re-running init only replaces graft's fenced section / owned skill file rather than making every listed command noisier for repos that already have the CLI.
• One shared sentence, cliFallbackNote(), is interpolated into instructionBody() and skillTemplate(). Agents that hit a missing binary are told to use npx -y @nanonets/graft in its place (example included); bunx / pnpm dlx / yarn dlx are named as equivalents. Commands stay graft ask so a global install keeps working unchanged.

Independent of #60 / #208 — the note is a static npx fallback, not lockfile detection. Those can merge later if instructions should follow --runner.

Test plan

• hosts-instructions and claude-skill-template assert the fallback wording
• graft init --agents claude cursor agents --no-global writes the note into AGENTS.md, .cursor/rules/graft.mdc, and SKILL.md
• graft init --dry-run still only lists paths
• npm run build
• related init/instruction tests green; full npm test matches origin/main aside from an unrelated viz --tabs failure when this worktree has no graft/ graph

Closes #61

Made with Cursor

[github-actions]

🌱 graft blast radius

2 areas changed → 3 areas can be affected. 10 dependent symbols, depth 2.
Tests: 2 areas updated their tests.

flowchart TB
  A0(("Host Initialization<br/>5 symbols"))
  A1(("CLI Wiring<br/>4 symbols"))
  A2(("Claude Initialization<br/>1 symbol"))
  classDef reached fill:#D9EDF3,stroke:#3AA7C9,stroke-width:1.5px,color:#0E313C;
  class A0,A1,A2 reached;

Loading

Can be affected	Symbols	Nearest hop	Reached from
Host Initialization	5	src/hosts/antigravity.ts:L36-L46 installAntigravitySkill — calls, depth 1	Skill Template, Host Instructions
CLI Wiring	4	src/cli.ts:L959-L1027 wireTarget — calls, depth 2	Skill Template, Host Instructions
Claude Initialization	1	src/claude/init.ts:L59-L90 runInit — calls, depth 1	Skill Template, Host Instructions

All 10 dependent symbols, grouped by area

Host Initialization — 5 symbols in 4 files

• src/hosts/antigravity.ts:L36-L46 — installAntigravitySkill (calls, depth 1)
  38: const content = skillTemplate();
• src/hosts/registry.ts:L1-L133 — registry.ts (references, depth 1)
  10: import { instructionBody, cursorRule, kiroSteering, windsurfRule } from './instructions.js';
• src/hosts/init.ts:L38-L90 — runHostsInit (calls, depth 2)
• src/hosts/init.ts:L1-L91 — init.ts (imports, depth 2)
• src/hosts/plan.ts:L1-L93 — plan.ts (imports, depth 2)

CLI Wiring — 4 symbols in 3 files

• src/cli.ts:L959-L1027 — wireTarget (calls, depth 2)
• src/cli.ts:L1-L1033 — cli.ts (imports, depth 2)
• src/upkeep-run.ts:L41-L46 — rewriteWiring (calls, depth 2)
• src/upkeep.ts:L1-L293 — upkeep.ts (imports, depth 2)

Claude Initialization — 1 symbol in 1 file

• src/claude/init.ts:L59-L90 — runInit (calls, depth 1)
  81: writeFileSync(skillPath, skillTemplate());

Test signal per changed area — 2 ✓

Reached = a node under a test path has a resolved edge into the changed symbol. It undercounts anything called indirectly — through a CLI, a spawned process or a dynamic import — so read a low ratio as “look here”, never as a coverage gate.

• ✓ Host Instructions — 1 of 2 reached · 1 test file changed here: test/hosts-instructions.test.ts
  • not reached: cliFallbackNote
• ✓ Skill Template — 1 of 1 reached · 1 test file changed here: test/claude-skill-template.test.ts

4 test suites also reference this code

4 symbols, kept out of the diagram and the table so they cannot crowd out the areas a reviewer has to look at.

• test/claude-init.test.ts
• test/hosts-antigravity.test.ts
• test/hosts-plan.test.ts
• test/hosts-registry.test.ts

⚠️ 1 changed file not in the graph (CHANGELOG.md) — no parser claims the extension, or the index predates the file.

_{graft blast · origin/main...HEAD · depth 2 · 5 changed files}

Open the interactive graph → — click an area to see its dependent symbols at file:line.