joycraft 0.7.15 → 0.7.17

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.
@@ -10,7 +10,7 @@ import {
10
10
  PI_SKILLS,
11
11
  SKILLS,
12
12
  TEMPLATES
13
- } from "./chunk-JYPBXPGD.js";
13
+ } from "./chunk-35RQLGKM.js";
14
14
  import {
15
15
  resolveUpdatePath
16
16
  } from "./chunk-OMFGDJW4.js";
@@ -345,18 +345,27 @@ function generateHookScript() {
345
345
  # Joycraft Safeguard \u2014 PreToolUse hook
346
346
  # Blocks dangerous Bash commands. Exit 2 = block the action.
347
347
  # Edit deny-patterns.txt to customize what's blocked.
348
+ #
349
+ # Claude Code passes no arguments: the hook payload arrives as JSON on stdin
350
+ # ({"tool_name":"Bash","tool_input":{"command":"..."},...}). The reason for a
351
+ # block goes to stderr, which is what the model sees on exit 2.
348
352
 
349
- TOOL_NAME="$1"
350
- # Read the full tool input from stdin
351
353
  INPUT=$(cat)
352
354
 
353
- # Only check Bash commands
354
- if [ "$TOOL_NAME" != "Bash" ]; then
355
- exit 0
355
+ if command -v jq >/dev/null 2>&1; then
356
+ TOOL_NAME=$(printf '%s' "$INPUT" | jq -r '.tool_name // empty' 2>/dev/null)
357
+ COMMAND=$(printf '%s' "$INPUT" | jq -r '.tool_input.command // .command // empty' 2>/dev/null)
358
+ else
359
+ # Fallback without jq: tolerate spaces around the colon and escaped quotes.
360
+ TOOL_NAME=$(printf '%s' "$INPUT" | grep -o '"tool_name"[[:space:]]*:[[:space:]]*"[^"]*"' | head -1 | sed 's/^"tool_name"[[:space:]]*:[[:space:]]*"//;s/"$//')
361
+ COMMAND=$(printf '%s' "$INPUT" | grep -o '"command"[[:space:]]*:[[:space:]]*"\\([^"\\\\]\\|\\\\.\\)*"' | head -1 | sed 's/^"command"[[:space:]]*:[[:space:]]*"//;s/"$//;s/\\\\"/"/g;s/\\\\\\\\/\\\\/g')
356
362
  fi
357
363
 
358
- # Extract the command from the JSON input
359
- COMMAND=$(echo "$INPUT" | grep -o '"command":"[^"]*"' | head -1 | sed 's/"command":"//;s/"$//')
364
+ # Only check Bash commands (the settings matcher already limits this hook to
365
+ # Bash; a payload that names another tool is passed through untouched).
366
+ if [ -n "$TOOL_NAME" ] && [ "$TOOL_NAME" != "Bash" ]; then
367
+ exit 0
368
+ fi
360
369
 
361
370
  if [ -z "$COMMAND" ]; then
362
371
  exit 0
@@ -373,9 +382,9 @@ while IFS= read -r pattern || [ -n "$pattern" ]; do
373
382
  [ -z "$pattern" ] && continue
374
383
  [[ "$pattern" == \\#* ]] && continue
375
384
 
376
- if echo "$COMMAND" | grep -qEi "$pattern"; then
377
- echo "Blocked by Joycraft Safeguard: command matches deny pattern '$pattern'"
378
- echo "Edit .claude/hooks/joycraft/deny-patterns.txt to modify blocked patterns."
385
+ if printf '%s' "$COMMAND" | grep -qEi "$pattern"; then
386
+ echo "Blocked by Joycraft Safeguard: command matches deny pattern '$pattern'" >&2
387
+ echo "Edit .claude/hooks/joycraft/deny-patterns.txt to modify blocked patterns." >&2
379
388
  exit 2
380
389
  fi
381
390
  done < "$PATTERNS_FILE"
@@ -487,6 +496,15 @@ try {
487
496
  `;
488
497
  }
489
498
 
499
+ // src/model-profile.ts
500
+ var MODEL_PROFILE_TEMPLATE_KEY = "reference/model-profile-claude-fable-5-1.md";
501
+ var MODEL_PROFILE_PATH = `docs/templates/${MODEL_PROFILE_TEMPLATE_KEY}`;
502
+ var MODEL_PROFILE_HARNESSES = Object.freeze(["claude", "pi", "omp"]);
503
+ var MODEL_PROFILE_CONTEXT_MAP_ROW = `| \`${MODEL_PROFILE_PATH}\` | Working with Claude Fable 5.1 \u2014 finishing whole tasks, scope, progress updates, prose |`;
504
+ function selectsModelProfile(harnesses) {
505
+ return harnesses.some((harness) => MODEL_PROFILE_HARNESSES.includes(harness));
506
+ }
507
+
490
508
  // src/bundle-inventory.ts
491
509
  var vendor = (path, harness, content, options = {}) => ({
492
510
  path,
@@ -506,6 +524,16 @@ var createOnce = (path) => ({
506
524
  active: true,
507
525
  installable: false
508
526
  });
527
+ var createOnceWithContent = (path, harness, content, options = {}) => ({
528
+ ...vendor(path, harness, content, options),
529
+ kind: "create-once"
530
+ });
531
+ var DENY_PATTERNS_PATH = ".claude/hooks/joycraft/deny-patterns.txt";
532
+ var EXAMPLE_EVAL_TEMPLATE_KEY = "evals/example-task.json";
533
+ var USER_OWNED_VENDOR_PATHS = [
534
+ DENY_PATTERNS_PATH,
535
+ `docs/templates/${EXAMPLE_EVAL_TEMPLATE_KEY}`
536
+ ];
509
537
  var patch = (path, harness, ownedKey, ownedRegion) => ({
510
538
  path,
511
539
  harness,
@@ -516,6 +544,20 @@ var patch = (path, harness, ownedKey, ownedRegion) => ({
516
544
  ...ownedKey ? { ownedKey } : {},
517
545
  ...ownedRegion ? { ownedRegion } : {}
518
546
  });
547
+ var TEMPLATE_HARNESS_GATES = {
548
+ // D6: keyed to the model, not the harness. The list lives in model-profile.ts
549
+ // so the memory-file pointer row is gated on exactly the same harnesses.
550
+ [MODEL_PROFILE_TEMPLATE_KEY]: MODEL_PROFILE_HARNESSES
551
+ };
552
+ function templateEntries(templates, selected2, gates = TEMPLATE_HARNESS_GATES) {
553
+ return Object.entries(templates).flatMap(([path, content]) => {
554
+ const gate = Object.prototype.hasOwnProperty.call(gates, path) ? gates[path] : void 0;
555
+ if (path === EXAMPLE_EVAL_TEMPLATE_KEY) return [createOnceWithContent(`docs/templates/${path}`, "shared", content)];
556
+ if (!gate) return [vendor(`docs/templates/${path}`, "shared", content)];
557
+ const owner = HARNESSES.find((harness) => gate.includes(harness) && selected2.includes(harness));
558
+ return owner ? [vendor(`docs/templates/${path}`, owner, content)] : [];
559
+ });
560
+ }
519
561
  function mapVendorFiles(harness, root, files, options = void 0) {
520
562
  return Object.entries(files).map(([name, content]) => {
521
563
  const relative = name.endsWith(".md") && root.endsWith("/skills") ? `${name.slice(0, -3)}/SKILL.md` : name;
@@ -526,7 +568,7 @@ function getBundleInventory(selection = HARNESSES) {
526
568
  const selected2 = sanitizeHarnesses(selection) ?? [...HARNESSES];
527
569
  const wants = (harness) => selected2.includes(harness);
528
570
  const entries = [
529
- ...Object.entries(TEMPLATES).map(([path, content]) => vendor(`docs/templates/${path}`, "shared", content)),
571
+ ...templateEntries(TEMPLATES, selected2),
530
572
  createOnce("CLAUDE.md"),
531
573
  createOnce("AGENTS.md"),
532
574
  vendor("docs/.joycraft/check.mjs", "shared", CHECKER_SOURCE, { executable: true, mode: 493 })
@@ -535,7 +577,7 @@ function getBundleInventory(selection = HARNESSES) {
535
577
  entries.push(...mapVendorFiles("claude", ".claude/skills", SKILLS));
536
578
  entries.push(
537
579
  vendor(".claude/hooks/joycraft/block-dangerous.sh", "claude", generateHookScript(), { executable: true, mode: 493 }),
538
- vendor(".claude/hooks/joycraft/deny-patterns.txt", "claude", generateDenyPatternsFile(), { executable: false }),
580
+ createOnceWithContent(DENY_PATTERNS_PATH, "claude", generateDenyPatternsFile(), { executable: false }),
539
581
  vendor(".claude/hooks/joycraft-version-check.mjs", "claude", generateClaudeSessionStartAdapter(), { executable: true, mode: 493 }),
540
582
  patch(".claude/settings.json", "claude", void 0, "hooks.SessionStart[command=node .claude/hooks/joycraft-version-check.mjs]"),
541
583
  patch(".claude/settings.json", "claude", void 0, "hooks.PreToolUse[command=.claude/hooks/joycraft/block-dangerous.sh]"),
@@ -857,6 +899,7 @@ function createUpdatePlan(input) {
857
899
  const actions = [];
858
900
  const groups = /* @__PURE__ */ new Map();
859
901
  const knownPaths = /* @__PURE__ */ new Set();
902
+ const backupDirectory = options.backupDirectory ?? `docs/.joycraft/local/replaced/${options.targetVersion ?? input.manifest.targetVersion}`;
860
903
  for (const entry of input.inventory) {
861
904
  knownPaths.add(entry.path);
862
905
  if (entry.kind === "create-once" && entry.content === void 0 || !entry.active || !entry.installable || entry.kind === "vendor" && entry.content === void 0) continue;
@@ -945,6 +988,7 @@ function createUpdatePlan(input) {
945
988
  const targetEqualsBase = baselineHash !== void 0 && targetHash === baselineHash;
946
989
  let kind;
947
990
  let reason;
991
+ let untouchedCreateOnce = false;
948
992
  if (currentContent === void 0) {
949
993
  if (verified) {
950
994
  kind = "preserve";
@@ -959,6 +1003,7 @@ function createUpdatePlan(input) {
959
1003
  } else if (old?.kind === "create-once" && !explicitReplacement(options, group.path)) {
960
1004
  kind = "preserve";
961
1005
  reason = "Create-once document is user-owned after its first creation; preserve local content.";
1006
+ untouchedCreateOnce = old.vendorHash !== "" && currentHash === old.vendorHash;
962
1007
  } else if (currentEqualsTarget) {
963
1008
  kind = old && verified ? "reconcile" : "adopt";
964
1009
  reason = kind === "reconcile" ? "Current bytes already equal target; reconcile manifest metadata." : "Exact trusted target match establishes vendor ownership.";
@@ -968,9 +1013,16 @@ function createUpdatePlan(input) {
968
1013
  } else if ((options.forceCustomized ?? []).includes(group.path)) {
969
1014
  kind = "replace";
970
1015
  reason = "Scoped init force selected this known customized path.";
1016
+ } else if (first.kind === "create-once" && !explicitReplacement(options, group.path)) {
1017
+ kind = "preserve";
1018
+ reason = "User-owned file; Joycraft does not change it after creating it.";
1019
+ if (old) nextManifest.files[group.path] = { ...old, kind: "create-once" };
971
1020
  } else if (targetEqualsBase) {
972
1021
  kind = "preserve";
973
1022
  reason = "Vendor target is unchanged; preserve the local-only edit.";
1023
+ } else if (first.kind === "vendor") {
1024
+ kind = "replace";
1025
+ reason = "Joycraft has a newer version of this edited file; the edited copy is saved as a backup.";
974
1026
  } else if (verified) {
975
1027
  kind = "conflict";
976
1028
  reason = "Current customization and target vendor content both differ from the verified base.";
@@ -983,6 +1035,7 @@ function createUpdatePlan(input) {
983
1035
  reason = "Explicit replacement selected for this customized path.";
984
1036
  }
985
1037
  const action = actionBase(group.path, kind, reason, currentContent, target, first.mode);
1038
+ if (untouchedCreateOnce && kind === "preserve") action.nonActionable = true;
986
1039
  if (target !== void 0 && ["replace", "create", "adopt", "conflict"].includes(kind)) action.content = bytes(target);
987
1040
  action.selected = selected(options, group.path, kind);
988
1041
  if (kind === "preserve" && currentContent === void 0 && verified && options.repair?.includes(group.path)) {
@@ -996,6 +1049,16 @@ function createUpdatePlan(input) {
996
1049
  }
997
1050
  if (kind === "conflict" && currentContent !== void 0 && target !== void 0) action.diff = diff(group.path, currentContent, target);
998
1051
  if (first.kind === "config-patch") action.patch = { ...first.ownedKey ? { ownedKey: first.ownedKey } : {}, ...first.ownedRegion ? { ownedRegion: first.ownedRegion } : {} };
1052
+ const overwritesEdits = currentContent !== void 0 && first.kind !== "config-patch" && !currentEqualsBase && !currentEqualsTarget && action.selected && (action.kind === "replace" || action.kind === "conflict" && action.resolution === "replace");
1053
+ if (overwritesEdits) {
1054
+ action.backupPath = `${backupDirectory}/${group.path}.bak`;
1055
+ add({
1056
+ ...actionBase(action.backupPath, "create", `Edited copy of ${group.path}, saved before Joycraft replaced it.`, void 0, currentContent, void 0),
1057
+ selected: true,
1058
+ content: bytes(currentContent),
1059
+ backupOf: group.path
1060
+ });
1061
+ }
999
1062
  add(action);
1000
1063
  if (action.selected && ["replace", "create", "adopt", "repair", "reconcile"].includes(action.kind)) addFile(nextManifest, group.path, first, targetHash, options.targetVersion ?? input.manifest.targetVersion);
1001
1064
  if (action.selected && action.kind === "conflict" && action.resolution === "replace") addFile(nextManifest, group.path, first, targetHash, options.targetVersion ?? input.manifest.targetVersion);
@@ -1079,6 +1142,7 @@ var LOCK_RELATIVE = `${LOCAL_DIR}/update.lock`;
1079
1142
  var JOURNAL_RELATIVE = `${LOCAL_DIR}/update-journal.json`;
1080
1143
  var BACKUPS_RELATIVE = `${LOCAL_DIR}/backups`;
1081
1144
  var LAST_SUCCESSFUL_RELATIVE = `${LOCAL_DIR}/last-successful.json`;
1145
+ var REPLACED_RELATIVE = `${LOCAL_DIR}/replaced`;
1082
1146
  var TransactionConflictError = class extends Error {
1083
1147
  conflictPath;
1084
1148
  constructor(message, conflictPath) {
@@ -1230,6 +1294,7 @@ function profileFor(plan, options) {
1230
1294
  return plan.nextManifest.profile;
1231
1295
  }
1232
1296
  function isControlPath(relativePath, profile) {
1297
+ if (relativePath.startsWith(`${REPLACED_RELATIVE}/`)) return false;
1233
1298
  const controls = [
1234
1299
  // Both authority locations are transaction control paths regardless of
1235
1300
  // the destination profile. A private transaction must not be able to
@@ -2188,6 +2253,7 @@ var KNOWN_DESCRIPTIONS = {
2188
2253
  "docs/discoveries/": "Session surprises worth remembering",
2189
2254
  "docs/templates/": "Bundled output and reference templates",
2190
2255
  "docs/backlog/": "Deferred work, one file per item",
2256
+ "docs/intent/": "Intent inbox \u2014 incoming work before a feature slug exists",
2191
2257
  "docs/research/": "Research notes and findings"
2192
2258
  };
2193
2259
  function listDirs(dir) {
@@ -2375,13 +2441,71 @@ This project uses [Joycraft](https://github.com/maksutovic/joycraft) for AI deve
2375
2441
 
2376
2442
  Run \`/joycraft-tune\` to see where your project stands and what to improve next.${invocationNote}`;
2377
2443
  }
2378
- function generateContextMapSection() {
2444
+ var CONTEXT_MAP_TABLE_HEADER = "| Document | Read it when\u2026 |\n|----------|---------------|";
2445
+ function generateContextMapSection(modelProfilePointer = false) {
2446
+ const row = modelProfilePointer ? `
2447
+ ${MODEL_PROFILE_CONTEXT_MAP_ROW}` : "";
2379
2448
  return `## Context Map
2380
2449
 
2381
2450
  Keep this file lean \u2014 link out, don't inline. Long-form reference docs live in \`docs/context/reference/\`; this table points to what to read on demand.
2382
2451
 
2383
- | Document | Read it when\u2026 |
2384
- |----------|---------------|`;
2452
+ ${CONTEXT_MAP_TABLE_HEADER}${row}`;
2453
+ }
2454
+ function sourceLines(content) {
2455
+ const lines = [];
2456
+ let offset = 0;
2457
+ while (offset < content.length) {
2458
+ const newline = content.indexOf("\n", offset);
2459
+ const end = newline === -1 ? content.length : newline + 1;
2460
+ const raw = content.slice(offset, newline === -1 ? content.length : newline);
2461
+ lines.push({ text: raw.replace(/\r$/, ""), start: offset, end });
2462
+ offset = end;
2463
+ }
2464
+ return lines;
2465
+ }
2466
+ function insertAfterLine(content, line, block, newline) {
2467
+ if (content[line.end - 1] === "\n") {
2468
+ return content.slice(0, line.end) + block + newline + content.slice(line.end);
2469
+ }
2470
+ return content + newline + block;
2471
+ }
2472
+ function insertModelProfilePointer(content) {
2473
+ if (content.includes(MODEL_PROFILE_PATH)) return content;
2474
+ const newline = content.includes("\r\n") ? "\r\n" : "\n";
2475
+ const lines = sourceLines(content);
2476
+ const header = lines.findIndex((line) => line.text.startsWith("## ") && /context\s*map/i.test(line.text));
2477
+ if (header === -1) {
2478
+ const section = generateContextMapSection(true).replace(/\n/g, newline);
2479
+ if (content === "") return section + newline;
2480
+ const base = content.endsWith("\n") ? content : content + newline;
2481
+ return base + newline + section + newline;
2482
+ }
2483
+ let sectionEnd = lines.length;
2484
+ for (let index = header + 1; index < lines.length; index++) {
2485
+ if (lines[index].text.startsWith("## ")) {
2486
+ sectionEnd = index;
2487
+ break;
2488
+ }
2489
+ }
2490
+ const isTableLine = (index) => lines[index].text.trim().startsWith("|");
2491
+ let tableStart = -1;
2492
+ for (let index = header + 1; index < sectionEnd; index++) {
2493
+ if (isTableLine(index)) {
2494
+ tableStart = index;
2495
+ break;
2496
+ }
2497
+ }
2498
+ if (tableStart !== -1) {
2499
+ let last = tableStart;
2500
+ while (last + 1 < sectionEnd && isTableLine(last + 1)) last++;
2501
+ return insertAfterLine(content, lines[last], MODEL_PROFILE_CONTEXT_MAP_ROW, newline);
2502
+ }
2503
+ let lastContent = header;
2504
+ for (let index = header + 1; index < sectionEnd; index++) {
2505
+ if (lines[index].text.trim() !== "") lastContent = index;
2506
+ }
2507
+ const table = ["", ...CONTEXT_MAP_TABLE_HEADER.split("\n"), MODEL_PROFILE_CONTEXT_MAP_ROW].join(newline);
2508
+ return insertAfterLine(content, lines[lastContent], table, newline);
2385
2509
  }
2386
2510
  function generateAreasSection() {
2387
2511
  return `## Areas
@@ -2432,7 +2556,7 @@ function generateCLAUDEMd(projectName2, stack, existingSkills = [], opts) {
2432
2556
  "",
2433
2557
  generateGotchasSection(),
2434
2558
  "",
2435
- generateContextMapSection(),
2559
+ generateContextMapSection(opts?.modelProfilePointer === true),
2436
2560
  "",
2437
2561
  generateGettingStartedSection(opts?.multiTool ?? false),
2438
2562
  ""
@@ -2491,7 +2615,7 @@ function generateKeyFilesSection2() {
2491
2615
  |------|---------|
2492
2616
  | _TODO_ | _Add key files_ |`;
2493
2617
  }
2494
- function generateAgentsMd(projectName2, stack, privateProfile = false, executionProfile, identity, projectDir) {
2618
+ function generateAgentsMd(projectName2, stack, privateProfile = false, executionProfile, identity, projectDir, modelProfilePointer = false) {
2495
2619
  const frameworkNote = stack.framework ? ` (${stack.framework})` : "";
2496
2620
  const langLabel = stack.language === "unknown" ? "" : ` | **Stack:** ${stack.language}${frameworkNote}`;
2497
2621
  const lines = [
@@ -2513,6 +2637,9 @@ function generateAgentsMd(projectName2, stack, privateProfile = false, execution
2513
2637
  generateDevelopmentSection(stack),
2514
2638
  ""
2515
2639
  ];
2640
+ if (modelProfilePointer) {
2641
+ lines.push(generateContextMapSection(true), "");
2642
+ }
2516
2643
  const identitySection = generateProductIdentitySection(identity);
2517
2644
  if (identitySection) {
2518
2645
  lines.push(identitySection, "");
@@ -2651,6 +2778,38 @@ focused without losing the thread.
2651
2778
  - Promote an item by turning it into a Feature Brief under
2652
2779
  \`docs/features/<slug>/\` when you're ready to build it.
2653
2780
  `;
2781
+ var INTENT_README = `# Intent inbox
2782
+
2783
+ An intent is a short note that describes a need before anyone commits to
2784
+ building it: a customer bug, a product idea, a ticket from another system, or
2785
+ an alert. Put intents here, one file per intent. Nothing needs to decide on a
2786
+ feature name first.
2787
+
2788
+ - One file per intent: \`docs/intent/YYYY-MM-DD-<short-name>.md\`.
2789
+ - Use the shape in \`docs/templates/INTENT_TEMPLATE.md\`: Author, Status,
2790
+ \`source\`, Problem, Proposed outcome, Affected users and systems,
2791
+ Constraints, Open questions.
2792
+ - A new intent starts with \`Status: untriaged\`. Joycraft skills update that
2793
+ line when they triage or consume the intent. The file stays here afterwards.
2794
+ - \`source:\` records where the intent came from, for example \`human\`,
2795
+ \`interview\`, \`linear:<id>\`, or \`alert:<name>\`. It is free text.
2796
+
2797
+ ## How intents map to Joycraft artifacts
2798
+
2799
+ Anthropic's AI-native development playbook names a chain of artifacts. Joycraft
2800
+ already has most of them under its own names. Nothing is renamed. Use the
2801
+ Joycraft names below.
2802
+
2803
+ | Playbook term | Joycraft artifact | Where it lives |
2804
+ |---------------|-------------------|----------------|
2805
+ | intent | intent | \`docs/intent/<name>.md\` |
2806
+ | spec | brief | \`docs/features/<slug>/brief.md\` |
2807
+ | plan | design + atomic specs | \`docs/features/<slug>/design.md\` and \`docs/features/<slug>/specs/\` |
2808
+
2809
+ An intent becomes a brief through \`/joycraft-new-feature\`, or a bugfix spec
2810
+ through \`/joycraft-bugfix\`. The brief, design, and specs keep their current
2811
+ names and folders.
2812
+ `;
2654
2813
  var CLAUDE_SETTINGS = ".claude/settings.json";
2655
2814
  var TS_CONFIG = "tsconfig.json";
2656
2815
  var KNOWN_GENERATED_DOCUMENTS = /* @__PURE__ */ new Set(["CLAUDE.md", "AGENTS.md"]);
@@ -2663,6 +2822,13 @@ function regularFile(root, relative) {
2663
2822
  return false;
2664
2823
  }
2665
2824
  }
2825
+ function isDirectory(root, relative) {
2826
+ try {
2827
+ return lstatSync2(join9(root, ...relative.split("/"))).isDirectory();
2828
+ } catch {
2829
+ return false;
2830
+ }
2831
+ }
2666
2832
  function existingPath(root, relative) {
2667
2833
  try {
2668
2834
  lstatSync2(join9(root, ...relative.split("/")));
@@ -2689,12 +2855,20 @@ function existingClaudeSkills(root, selected2) {
2689
2855
  return [];
2690
2856
  }
2691
2857
  }
2858
+ function sharesAgentsMd(harnesses) {
2859
+ return harnesses.some((harness) => harness !== "claude");
2860
+ }
2861
+ function memoryFilePath(harnesses) {
2862
+ return sharesAgentsMd(harnesses) ? "AGENTS.md" : "CLAUDE.md";
2863
+ }
2692
2864
  function generatorContent(root, path, harnesses, profile, stack, existingSkills, executionProfile) {
2693
- const multiTool = harnesses.some((harness) => harness !== "claude");
2865
+ const multiTool = sharesAgentsMd(harnesses);
2866
+ const modelProfilePointer = selectsModelProfile(harnesses);
2694
2867
  if (path === "CLAUDE.md") {
2695
2868
  return multiTool ? generateClaudeMdPointer() : generateCLAUDEMd(projectName(root), stack, existingSkills, {
2696
2869
  privateProfile: profile === "private",
2697
- projectDir: root
2870
+ projectDir: root,
2871
+ modelProfilePointer
2698
2872
  });
2699
2873
  }
2700
2874
  if (path === "AGENTS.md") {
@@ -2702,7 +2876,8 @@ function generatorContent(root, path, harnesses, profile, stack, existingSkills,
2702
2876
  privateProfile: profile === "private",
2703
2877
  multiTool: true,
2704
2878
  executionProfile,
2705
- projectDir: root
2879
+ projectDir: root,
2880
+ modelProfilePointer
2706
2881
  }) : generateAgentsMd(projectName(root), stack, profile === "private", executionProfile, void 0, root);
2707
2882
  }
2708
2883
  return void 0;
@@ -2714,10 +2889,7 @@ function materializeDocuments(input, existingSkills) {
2714
2889
  const exists = regularFile(input.root, entry.path);
2715
2890
  const recorded = input.manifest.files[entry.path] !== void 0;
2716
2891
  const forceKnown = input.force === true && KNOWN_GENERATED_DOCUMENTS.has(entry.path);
2717
- if (entry.content !== void 0) {
2718
- if (!exists || forceKnown) return [entry];
2719
- return [];
2720
- }
2892
+ if (entry.content !== void 0) return [entry];
2721
2893
  const content = generatorContent(
2722
2894
  input.root,
2723
2895
  entry.path,
@@ -2775,6 +2947,20 @@ function freshBacklogEntry(input) {
2775
2947
  content: BACKLOG_README
2776
2948
  };
2777
2949
  }
2950
+ function freshIntentEntry(input) {
2951
+ if (!input.freshInstall) return void 0;
2952
+ if (existingPath(input.root, "docs/intent") && !isDirectory(input.root, "docs/intent")) return void 0;
2953
+ if (existingPath(input.root, "docs/intent/README.md")) return void 0;
2954
+ return {
2955
+ path: "docs/intent/README.md",
2956
+ harness: "shared",
2957
+ kind: "create-once",
2958
+ ownership: "managed",
2959
+ active: true,
2960
+ installable: true,
2961
+ content: INTENT_README
2962
+ };
2963
+ }
2778
2964
  function parseSettings(raw) {
2779
2965
  try {
2780
2966
  const parsed = JSON.parse(raw);
@@ -2967,6 +3153,29 @@ function tsconfigPatch(input, diagnostics) {
2967
3153
  reason: "Exclude the installed Pi runtime from the project TypeScript program while preserving the existing tsconfig bytes."
2968
3154
  };
2969
3155
  }
3156
+ function contextMapPointerPatch(input, entries, diagnostics) {
3157
+ if (!selectsModelProfile(input.harnesses)) return void 0;
3158
+ const memory = memoryFilePath(input.harnesses);
3159
+ if (!regularFile(input.root, memory)) return void 0;
3160
+ if (entries.some((entry) => entry.path === memory && entry.content !== void 0)) return void 0;
3161
+ let raw;
3162
+ try {
3163
+ raw = readFileSync7(join9(input.root, memory), "utf8");
3164
+ } catch {
3165
+ diagnostics.push(`${memory} could not be read; add the model profile row to its Context Map manually.`);
3166
+ return void 0;
3167
+ }
3168
+ const next = insertModelProfilePointer(raw);
3169
+ if (next === raw) return void 0;
3170
+ return {
3171
+ path: memory,
3172
+ kind: "write",
3173
+ content: next,
3174
+ currentPresent: true,
3175
+ rawPrecondition: rawFileHash(raw),
3176
+ reason: "Add one Context Map row pointing at the Claude Fable 5.1 model profile; every other byte is preserved."
3177
+ };
3178
+ }
2970
3179
  function materializeFreshInstallInventory(input) {
2971
3180
  const diagnostics = [];
2972
3181
  const existingSkills = existingClaudeSkills(input.root, input.harnesses);
@@ -2974,13 +3183,15 @@ function materializeFreshInstallInventory(input) {
2974
3183
  const known = new Set(entries.map((entry) => entry.path));
2975
3184
  const backlog = freshBacklogEntry(input);
2976
3185
  if (backlog && !known.has(backlog.path)) entries.push(backlog);
3186
+ const intent = freshIntentEntry(input);
3187
+ if (intent && !known.has(intent.path)) entries.push(intent);
2977
3188
  const settings = freshSettingsEntry(input);
2978
3189
  if (settings && !known.has(settings.path)) entries.push(settings);
2979
3190
  const directories = [];
2980
3191
  if (input.freshInstall) {
2981
- for (const relative of ["docs/context", "docs/backlog"]) {
3192
+ for (const relative of ["docs/context", "docs/backlog", "docs/intent"]) {
2982
3193
  if (!existingPath(input.root, relative)) directories.push(relative);
2983
- else if (!regularFile(input.root, relative)) {
3194
+ else {
2984
3195
  try {
2985
3196
  if (!lstatSync2(join9(input.root, ...relative.split("/"))).isDirectory()) {
2986
3197
  diagnostics.push(`${relative} exists but is not a directory; preserving it.`);
@@ -2991,7 +3202,11 @@ function materializeFreshInstallInventory(input) {
2991
3202
  }
2992
3203
  }
2993
3204
  }
2994
- const patchOperations = [settingsPatch(input, diagnostics), tsconfigPatch(input, diagnostics)].filter((operation) => operation !== void 0);
3205
+ const patchOperations = [
3206
+ settingsPatch(input, diagnostics),
3207
+ tsconfigPatch(input, diagnostics),
3208
+ contextMapPointerPatch(input, entries, diagnostics)
3209
+ ].filter((operation) => operation !== void 0);
2995
3210
  return {
2996
3211
  entries,
2997
3212
  setup: { directories, existingSkills, patchOperations },
@@ -3057,6 +3272,9 @@ function evaluateAutoSafeEligibility(input) {
3057
3272
  reject("The update plan changes user configuration.");
3058
3273
  }
3059
3274
  if ((input.replaceCustomized?.length ?? 0) > 0) reject("Customized replacements require an explicit update.");
3275
+ if (input.plan.actions.some((action) => action.selected && action.backupPath !== void 0)) {
3276
+ reject("Replacing edited files requires an explicit update.");
3277
+ }
3060
3278
  if ((input.repair?.length ?? 0) > 0) reject("Repairs require an explicit update.");
3061
3279
  if (input.migration) reject("Migrations require an explicit update.");
3062
3280
  if (input.legacyBridge) reject("Legacy bridge adoption requires an explicit update.");
@@ -3192,9 +3410,12 @@ function legacyHarnesses(root) {
3192
3410
  }
3193
3411
  return void 0;
3194
3412
  }
3413
+ function harnessTreeEntry(entry, harness) {
3414
+ return entry.harness === harness && entry.content !== void 0 && !entry.path.startsWith("docs/templates/");
3415
+ }
3195
3416
  function recognizedHarnesses(root) {
3196
3417
  const inventory = getBundleInventory(HARNESSES);
3197
- return HARNESSES.filter((harness) => inventory.some((entry) => entry.harness === harness && entry.content !== void 0 && regularFile2(root, entry.path)));
3418
+ return HARNESSES.filter((harness) => inventory.some((entry) => harnessTreeEntry(entry, harness) && regularFile2(root, entry.path)));
3198
3419
  }
3199
3420
  function legacyMigrationOperations(root, localSettings) {
3200
3421
  const sources = [STATE_PATH, LEGACY_CLAUDE_STATE_PATH, LEGACY_VERSION_FILE];
@@ -3345,11 +3566,20 @@ function localSettingsFromAdoption(root, entries, bundle, profile) {
3345
3566
  return { manifest: adopted.manifest, localSettings: adopted.localSettings, conflicts: adopted.conflicts };
3346
3567
  }
3347
3568
  function pathsForOutcome(plan) {
3348
- const applied = plan.actions.filter((action) => action.selected && ["replace", "create", "repair", "delete", "conflict"].includes(action.kind)).map((action) => action.path);
3569
+ const applied = plan.actions.filter((action) => action.selected && !action.backupOf && ["replace", "create", "repair", "delete", "conflict"].includes(action.kind)).map((action) => action.path);
3570
+ const replaced = plan.actions.filter((action) => action.selected && action.backupPath !== void 0).map((action) => ({ path: action.path, backup: action.backupPath }));
3349
3571
  const resolved = new Set(plan.actions.filter((action) => action.kind === "conflict" && action.selected && action.resolution === "replace").map((action) => action.path));
3350
3572
  const preserved = plan.preserved.filter((entry) => !resolved.has(entry.path)).filter((entry) => !plan.actions.some((action) => action.path === entry.path && action.nonActionable === true)).map((entry) => entry.path);
3351
3573
  const conflicts = plan.conflicts.filter((action) => !resolved.has(action.path)).map((action) => action.path);
3352
- return { applied: [...new Set(applied)], preserved: [...new Set(preserved)], conflicts: [...new Set(conflicts)] };
3574
+ return { applied: [...new Set(applied)], preserved: [...new Set(preserved)], conflicts: [...new Set(conflicts)], replaced };
3575
+ }
3576
+ function backupDirectoryFor(root, now = /* @__PURE__ */ new Date()) {
3577
+ const pad = (value) => String(value).padStart(2, "0");
3578
+ const stamp = `${now.getUTCFullYear()}${pad(now.getUTCMonth() + 1)}${pad(now.getUTCDate())}-${pad(now.getUTCHours())}${pad(now.getUTCMinutes())}${pad(now.getUTCSeconds())}`;
3579
+ const base = `docs/.joycraft/local/replaced/${stamp}`;
3580
+ let candidate = base;
3581
+ for (let suffix = 2; existsSync8(join10(root, ...candidate.split("/"))); suffix += 1) candidate = `${base}-${suffix}`;
3582
+ return candidate;
3353
3583
  }
3354
3584
  function setupPatchAction(operation) {
3355
3585
  return {
@@ -3392,7 +3622,7 @@ function profileBookkeepingActions(root, profile) {
3392
3622
  function selectedHarnessIgnoreWarning(root, harnesses) {
3393
3623
  const warnings = [];
3394
3624
  for (const harness of harnesses) {
3395
- const candidate = getBundleInventory([harness]).find((entry) => entry.harness === harness && entry.content !== void 0)?.path;
3625
+ const candidate = getBundleInventory([harness]).find((entry) => harnessTreeEntry(entry, harness))?.path;
3396
3626
  if (!candidate) continue;
3397
3627
  const top = candidate.split("/")[0];
3398
3628
  let localBroadIgnore = false;
@@ -3584,7 +3814,8 @@ async function update(dir, options = {}) {
3584
3814
  replaceCustomized: [...new Set(replaceCustomized)],
3585
3815
  forceCustomized: [...new Set(forceCustomized)],
3586
3816
  repair: options.repair,
3587
- baseManifestDigest: existingManifest ? void 0 : null
3817
+ baseManifestDigest: existingManifest ? void 0 : null,
3818
+ backupDirectory: backupDirectoryFor(root)
3588
3819
  }
3589
3820
  });
3590
3821
  plan.diagnostics.push(...materialized.diagnostics.map((diagnostic) => /settings\.json is malformed/i.test(diagnostic) && !/fix the json/i.test(diagnostic) ? `${diagnostic} Fix the JSON before retrying.` : diagnostic));
@@ -3624,12 +3855,13 @@ async function update(dir, options = {}) {
3624
3855
  authorityTransition: authorityTransition !== void 0
3625
3856
  });
3626
3857
  if (!eligibility.eligible) {
3627
- return outcome(selected2.conflicts.length > 0 ? "conflict" : "invalid", {
3858
+ const needsReview = [.../* @__PURE__ */ new Set([...selected2.conflicts, ...selected2.replaced.map((entry) => entry.path)])];
3859
+ return outcome(needsReview.length > 0 ? "conflict" : "invalid", {
3628
3860
  targetVersion: bundle.version,
3629
3861
  profile: authority.profile,
3630
3862
  harnesses,
3631
3863
  preserved: selected2.preserved,
3632
- conflicts: selected2.conflicts,
3864
+ conflicts: needsReview,
3633
3865
  diagnostics: [...plan.diagnostics, ...eligibility.diagnostics],
3634
3866
  plan,
3635
3867
  localSettings,
@@ -3647,6 +3879,7 @@ async function update(dir, options = {}) {
3647
3879
  applied: [],
3648
3880
  preserved: selected2.preserved,
3649
3881
  conflicts: selected2.conflicts,
3882
+ replaced: selected2.replaced,
3650
3883
  diagnostics: plan.diagnostics,
3651
3884
  plan,
3652
3885
  localSettings,
@@ -3712,6 +3945,7 @@ async function update(dir, options = {}) {
3712
3945
  applied: actualApplied,
3713
3946
  preserved: selected2.preserved,
3714
3947
  conflicts: [.../* @__PURE__ */ new Set([...selected2.conflicts, ...transaction.conflicts])],
3948
+ replaced: transaction.status === "applied" ? selected2.replaced : [],
3715
3949
  diagnostics,
3716
3950
  transaction,
3717
3951
  plan,
@@ -3732,24 +3966,34 @@ function formatUpdateOutcome(result, json = false) {
3732
3966
  applied: result.applied,
3733
3967
  preserved: result.preserved,
3734
3968
  conflicts: result.conflicts,
3969
+ replaced: result.replaced ?? [],
3735
3970
  diagnostics: result.diagnostics,
3736
3971
  registry: result.registry,
3737
3972
  existingSkills: result.existingSkills,
3738
3973
  transaction: result.transaction
3739
3974
  });
3740
3975
  }
3741
- const lines = [`Joycraft update: ${result.status}.`];
3742
- if (result.targetVersion) lines.push(` Target: ${result.targetVersion}`);
3976
+ const target = result.targetVersion;
3977
+ const headline = result.status === "applied" && target ? `Joycraft updated to ${target}.` : (result.status === "noop" || result.status === "preserved") && target ? `Joycraft is up to date (${target}).` : result.status === "conflict" ? "Joycraft update needs your review." : `Joycraft update: ${result.status}.`;
3978
+ const lines = [headline];
3979
+ if (target && !headline.includes(target)) lines.push(` Target: ${target}`);
3743
3980
  if (result.applied.length) lines.push(` Applied: ${result.applied.length}`);
3744
- if (result.preserved.length) lines.push(` Preserved customizations: ${result.preserved.join(", ")}`);
3745
- if (result.conflicts.length) lines.push(` Pending conflicts: ${result.conflicts.join(", ")}`);
3981
+ const replaced = result.replaced ?? [];
3982
+ if (replaced.length) {
3983
+ const first = replaced[0];
3984
+ const directory = first.backup.slice(0, first.backup.length - `${first.path}.bak`.length);
3985
+ lines.push(` Replaced your edited copies (saved in ${directory}): ${replaced.map((entry) => entry.path).join(", ")}`);
3986
+ }
3987
+ if (result.preserved.length) lines.push(` Kept your versions: ${result.preserved.join(", ")}`);
3988
+ if (result.conflicts.length) lines.push(` Needs review: ${result.conflicts.join(", ")}`);
3746
3989
  for (const diagnostic of result.diagnostics) lines.push(` \u26A0 ${diagnostic}`);
3747
3990
  return lines.join("\n");
3748
3991
  }
3749
3992
 
3750
3993
  export {
3751
3994
  updateStatusExitCode,
3995
+ backupDirectoryFor,
3752
3996
  update,
3753
3997
  formatUpdateOutcome
3754
3998
  };
3755
- //# sourceMappingURL=chunk-PR4QDKPL.js.map
3999
+ //# sourceMappingURL=chunk-YLWBDXF4.js.map