@phren/cli 0.1.45 → 0.1.47

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.
Files changed (52) hide show
  1. package/dist/agents/providers/herdr.d.ts +18 -0
  2. package/dist/agents/providers/herdr.js +94 -0
  3. package/dist/agents/providers/spawner.d.ts +13 -0
  4. package/dist/agents/providers/spawner.js +63 -0
  5. package/dist/agents/registry.d.ts +28 -0
  6. package/dist/agents/registry.js +82 -0
  7. package/dist/agents/types.d.ts +51 -0
  8. package/dist/agents/types.js +42 -0
  9. package/dist/cli/namespaces-utils.d.ts +5 -0
  10. package/dist/cli/namespaces-utils.js +12 -12
  11. package/dist/cli/search.js +29 -0
  12. package/dist/cli-registry.d.ts +1 -1
  13. package/dist/cli-registry.js +1 -0
  14. package/dist/content/learning.js +24 -1
  15. package/dist/editor/buffer.d.ts +48 -0
  16. package/dist/editor/buffer.js +312 -0
  17. package/dist/editor/launch.d.ts +41 -0
  18. package/dist/editor/launch.js +92 -0
  19. package/dist/editor/save.d.ts +15 -0
  20. package/dist/editor/save.js +70 -0
  21. package/dist/generated/memory-ui-graph.browser.js +69 -69
  22. package/dist/graph-core/model.js +99 -9
  23. package/dist/memory-ui-graph.runtime.js +69 -69
  24. package/dist/phren-art.d.ts +7 -0
  25. package/dist/phren-art.js +6 -41
  26. package/dist/shared/lookup-tail.d.ts +35 -0
  27. package/dist/shared/lookup-tail.js +100 -0
  28. package/dist/shell/editor-view.d.ts +8 -0
  29. package/dist/shell/editor-view.js +67 -0
  30. package/dist/shell/entry.js +31 -4
  31. package/dist/shell/graph/agents.d.ts +48 -0
  32. package/dist/shell/graph/agents.js +152 -0
  33. package/dist/shell/graph/controller.d.ts +40 -2
  34. package/dist/shell/graph/controller.js +149 -12
  35. package/dist/shell/graph/graph-view.d.ts +7 -0
  36. package/dist/shell/graph/graph-view.js +227 -50
  37. package/dist/shell/graph/layout.d.ts +21 -2
  38. package/dist/shell/graph/layout.js +79 -11
  39. package/dist/shell/graph/watch.d.ts +71 -0
  40. package/dist/shell/graph/watch.js +153 -0
  41. package/dist/shell/input.d.ts +24 -0
  42. package/dist/shell/input.js +76 -7
  43. package/dist/shell/render-api.js +1 -0
  44. package/dist/shell/render.js +12 -2
  45. package/dist/shell/shell.d.ts +25 -1
  46. package/dist/shell/shell.js +134 -5
  47. package/dist/shell/startup.d.ts +3 -0
  48. package/dist/shell/startup.js +8 -0
  49. package/dist/shell/view.d.ts +5 -1
  50. package/dist/shell/view.js +80 -75
  51. package/dist/ui/server.js +6 -56
  52. package/package.json +1 -1
@@ -0,0 +1,71 @@
1
+ /**
2
+ * Watch mode for the terminal graph.
3
+ *
4
+ * Every memory phren lands on — an MCP `search_knowledge` hit, a memory a
5
+ * hook injected before a prompt, a finding just written — is appended to
6
+ * `.runtime/lookup-events.jsonl`. Watch mode tails that log so a graph open
7
+ * in one terminal lights up as an agent works in another: the node pulses,
8
+ * the camera flies to it, and the finding's full text lands in the pane.
9
+ *
10
+ * This module owns the event plumbing only. Drawing lives in graph-view.ts
11
+ * and camera/selection in controller.ts.
12
+ */
13
+ import { type LookupEvent } from "../../governance/activity.js";
14
+ /** How long a touched node stays lit, in ms. */
15
+ export declare const HEAT_MS = 6000;
16
+ /** Events kept for the activity feed. */
17
+ export declare const ACTIVITY_LIMIT = 60;
18
+ export interface ActivityItem {
19
+ event: LookupEvent;
20
+ /** Wall-clock ms when this arrived; drives heat decay and the feed's age column. */
21
+ seenAt: number;
22
+ /** Graph node this event points at, when resolvable. */
23
+ nodeId?: string;
24
+ /** True for rows loaded as history rather than seen live. */
25
+ historical: boolean;
26
+ }
27
+ export interface GraphWatchOptions {
28
+ pollMs?: number;
29
+ /** Injected in tests so no real file or timer is needed. */
30
+ tail?: {
31
+ poll: () => LookupEvent[];
32
+ };
33
+ backfill?: (phrenPath: string, limit: number) => LookupEvent[];
34
+ now?: () => number;
35
+ }
36
+ export declare class GraphWatch {
37
+ readonly phrenPath: string;
38
+ /** Newest first. */
39
+ activity: ActivityItem[];
40
+ private heat;
41
+ private tail;
42
+ private timer;
43
+ private onEvents;
44
+ private readonly pollMs;
45
+ private readonly injectedTail?;
46
+ private readonly backfillFn;
47
+ private readonly now;
48
+ constructor(phrenPath: string, opts?: GraphWatchOptions);
49
+ get running(): boolean;
50
+ /**
51
+ * Begin tailing. Recent history is loaded into the feed immediately but is
52
+ * never treated as live: it does not pulse and never moves the camera.
53
+ */
54
+ start(onEvents: (items: ActivityItem[]) => void): void;
55
+ stop(): void;
56
+ /** Drain the log. Returns the new items, newest last, and lights their nodes. */
57
+ poll(): ActivityItem[];
58
+ /** 1 right after a node was touched, easing to 0 over HEAT_MS. */
59
+ heatOf(nodeId: string): number;
60
+ /** True while any node is still lit, so the host keeps animating. */
61
+ get hot(): boolean;
62
+ clearActivity(): void;
63
+ }
64
+ /**
65
+ * The graph node an event points at. Findings carry a precomputed `nodeId`
66
+ * (the same id `buildGraph` assigns); everything else falls back to the
67
+ * project node, whose id is the project name.
68
+ */
69
+ export declare function targetNodeId(event: LookupEvent): string | undefined;
70
+ /** "just now", "4s", "2m" — the feed's age column. */
71
+ export declare function formatAge(ms: number): string;
@@ -0,0 +1,153 @@
1
+ /**
2
+ * Watch mode for the terminal graph.
3
+ *
4
+ * Every memory phren lands on — an MCP `search_knowledge` hit, a memory a
5
+ * hook injected before a prompt, a finding just written — is appended to
6
+ * `.runtime/lookup-events.jsonl`. Watch mode tails that log so a graph open
7
+ * in one terminal lights up as an agent works in another: the node pulses,
8
+ * the camera flies to it, and the finding's full text lands in the pane.
9
+ *
10
+ * This module owns the event plumbing only. Drawing lives in graph-view.ts
11
+ * and camera/selection in controller.ts.
12
+ */
13
+ import { lookupEventsLogFile } from "../../shared.js";
14
+ import { readRecentLookups } from "../../governance/activity.js";
15
+ import { LookupTail } from "../../shared/lookup-tail.js";
16
+ /** How long a touched node stays lit, in ms. */
17
+ export const HEAT_MS = 6000;
18
+ /** Events kept for the activity feed. */
19
+ export const ACTIVITY_LIMIT = 60;
20
+ const DEFAULT_POLL_MS = 700;
21
+ /** Backfilled rows shown when watch mode starts, so the feed is never empty. */
22
+ const BACKFILL = 12;
23
+ export class GraphWatch {
24
+ phrenPath;
25
+ /** Newest first. */
26
+ activity = [];
27
+ heat = new Map();
28
+ tail = null;
29
+ timer = null;
30
+ onEvents = null;
31
+ pollMs;
32
+ injectedTail;
33
+ backfillFn;
34
+ now;
35
+ constructor(phrenPath, opts = {}) {
36
+ this.phrenPath = phrenPath;
37
+ this.pollMs = opts.pollMs ?? DEFAULT_POLL_MS;
38
+ this.injectedTail = opts.tail;
39
+ this.backfillFn = opts.backfill ?? readRecentLookups;
40
+ this.now = opts.now ?? (() => Date.now());
41
+ }
42
+ get running() {
43
+ return this.tail !== null;
44
+ }
45
+ /**
46
+ * Begin tailing. Recent history is loaded into the feed immediately but is
47
+ * never treated as live: it does not pulse and never moves the camera.
48
+ */
49
+ start(onEvents) {
50
+ if (this.tail)
51
+ return;
52
+ this.onEvents = onEvents;
53
+ this.tail = this.injectedTail ?? new LookupTail(lookupEventsLogFile(this.phrenPath));
54
+ if (!this.activity.length) {
55
+ try {
56
+ const seenAt = this.now();
57
+ this.activity = this.backfillFn(this.phrenPath, BACKFILL).map((event) => ({
58
+ event,
59
+ seenAt,
60
+ nodeId: targetNodeId(event),
61
+ historical: true,
62
+ }));
63
+ }
64
+ catch {
65
+ this.activity = [];
66
+ }
67
+ }
68
+ if (!this.injectedTail) {
69
+ this.timer = setInterval(() => this.poll(), this.pollMs);
70
+ this.timer.unref?.();
71
+ }
72
+ }
73
+ stop() {
74
+ if (this.timer) {
75
+ clearInterval(this.timer);
76
+ this.timer = null;
77
+ }
78
+ this.tail = null;
79
+ this.onEvents = null;
80
+ this.heat.clear();
81
+ }
82
+ /** Drain the log. Returns the new items, newest last, and lights their nodes. */
83
+ poll() {
84
+ if (!this.tail)
85
+ return [];
86
+ let events;
87
+ try {
88
+ events = this.tail.poll();
89
+ }
90
+ catch {
91
+ return [];
92
+ }
93
+ if (!events.length)
94
+ return [];
95
+ const seenAt = this.now();
96
+ const items = events.map((event) => ({ event, seenAt, nodeId: targetNodeId(event), historical: false }));
97
+ for (const item of items) {
98
+ if (item.nodeId)
99
+ this.heat.set(item.nodeId, seenAt);
100
+ }
101
+ this.activity = [...items].reverse().concat(this.activity).slice(0, ACTIVITY_LIMIT);
102
+ this.onEvents?.(items);
103
+ return items;
104
+ }
105
+ /** 1 right after a node was touched, easing to 0 over HEAT_MS. */
106
+ heatOf(nodeId) {
107
+ const at = this.heat.get(nodeId);
108
+ if (at === undefined)
109
+ return 0;
110
+ const age = this.now() - at;
111
+ if (age >= HEAT_MS) {
112
+ this.heat.delete(nodeId);
113
+ return 0;
114
+ }
115
+ return 1 - age / HEAT_MS;
116
+ }
117
+ /** True while any node is still lit, so the host keeps animating. */
118
+ get hot() {
119
+ if (!this.heat.size)
120
+ return false;
121
+ const now = this.now();
122
+ for (const at of this.heat.values()) {
123
+ if (now - at < HEAT_MS)
124
+ return true;
125
+ }
126
+ this.heat.clear();
127
+ return false;
128
+ }
129
+ clearActivity() {
130
+ this.activity = [];
131
+ this.heat.clear();
132
+ }
133
+ }
134
+ /**
135
+ * The graph node an event points at. Findings carry a precomputed `nodeId`
136
+ * (the same id `buildGraph` assigns); everything else falls back to the
137
+ * project node, whose id is the project name.
138
+ */
139
+ export function targetNodeId(event) {
140
+ if (event.nodeId)
141
+ return event.nodeId;
142
+ return event.project || undefined;
143
+ }
144
+ /** "just now", "4s", "2m" — the feed's age column. */
145
+ export function formatAge(ms) {
146
+ if (ms < 1500)
147
+ return "now";
148
+ if (ms < 60_000)
149
+ return `${Math.round(ms / 1000)}s`;
150
+ if (ms < 3_600_000)
151
+ return `${Math.round(ms / 60_000)}m`;
152
+ return `${Math.round(ms / 3_600_000)}h`;
153
+ }
@@ -34,6 +34,9 @@ export interface NavigationHost extends PaletteHost {
34
34
  name?: string;
35
35
  text?: string;
36
36
  line?: string;
37
+ path?: string;
38
+ scopeType?: string;
39
+ storePath?: string;
37
40
  }[];
38
41
  startInput(ctx: string, initial: string): void;
39
42
  inputMqId: string;
@@ -42,7 +45,25 @@ export interface NavigationHost extends PaletteHost {
42
45
  setFilter(value: string): void;
43
46
  /** The knowledge-graph view's controller (created on first use). */
44
47
  graph(): GraphController;
48
+ /** Run something with the terminal released; false when the host cannot. */
49
+ suspend(fn: () => Promise<void> | void): Promise<boolean>;
50
+ /** Open a file in the shell's own modal editor. */
51
+ openEditor(filePath: string, label: string, kind: "skill" | "claude", scope?: string): boolean;
45
52
  }
53
+ /**
54
+ * The file `e` and `E` edit for the current view. Skills edit their own
55
+ * markdown; a project edits the CLAUDE.md the store owns and symlinks into the
56
+ * repo, so editing here reaches every linked checkout.
57
+ */
58
+ export declare function editTargetFor(host: NavigationHost, item: {
59
+ name?: string;
60
+ path?: string;
61
+ storePath?: string;
62
+ } | undefined): {
63
+ path: string;
64
+ label: string;
65
+ kind: "skill" | "claude";
66
+ } | null;
46
67
  export declare function executePalette(host: PaletteHost, input: string): Promise<void>;
47
68
  export declare function completeInput(line: string, phrenPath: string, profile: string, state: ShellState): string[];
48
69
  export declare function getListItems(phrenPath: string, profile: string, state: ShellState, healthLineCount: number): {
@@ -50,6 +71,9 @@ export declare function getListItems(phrenPath: string, profile: string, state:
50
71
  name?: string;
51
72
  text?: string;
52
73
  line?: string;
74
+ path?: string;
75
+ scopeType?: string;
76
+ storePath?: string;
53
77
  }[];
54
78
  /**
55
79
  * Handle p/b/l/m/s/k/h shortcut keys that switch the active view.
@@ -13,10 +13,32 @@ import { consolidateProjectFindings } from "../governance/policy.js";
13
13
  import { style } from "./render.js";
14
14
  import { SUB_VIEWS, TAB_ICONS } from "./types.js";
15
15
  import { getProjectSkills, getHookEntries, writeInstallPreferences } from "./view.js";
16
+ import { resolveProjectStorePath } from "../cli/namespaces-utils.js";
17
+ import { openInEditor } from "../editor/launch.js";
16
18
  import { removeSkillPath, setSkillEnabledAndSync } from "../skill/files.js";
17
19
  import { resultMsg, editDistance, tokenize, expandIds, normalizeSection, tasksByFilter, queueByFilter, } from "./palette.js";
18
20
  import { errorMessage } from "../utils.js";
19
21
  import { logger } from "../logger.js";
22
+ /**
23
+ * The file `e` and `E` edit for the current view. Skills edit their own
24
+ * markdown; a project edits the CLAUDE.md the store owns and symlinks into the
25
+ * repo, so editing here reaches every linked checkout.
26
+ */
27
+ export function editTargetFor(host, item) {
28
+ if (host.state.view === "Skills") {
29
+ if (!item?.path)
30
+ return null;
31
+ return { path: item.path, label: item.name ?? path.basename(item.path), kind: "skill" };
32
+ }
33
+ if (host.state.view === "Projects") {
34
+ const project = item?.name ?? host.state.project;
35
+ if (!project)
36
+ return null;
37
+ const store = resolveProjectStorePath(host.phrenPath, project);
38
+ return { path: path.join(store, project, "CLAUDE.md"), label: `${project}/CLAUDE.md`, kind: "claude" };
39
+ }
40
+ return null;
41
+ }
20
42
  function taskFileForProject(phrenPath, project) {
21
43
  return resolveTaskFilePath(phrenPath, project)
22
44
  ?? canonicalTaskFilePath(phrenPath, project)
@@ -30,7 +52,7 @@ export async function executePalette(host, input) {
30
52
  const command = (parts[0] || "").toLowerCase();
31
53
  if (command === "help") {
32
54
  host.showHelp = true;
33
- host.setMessage(" Showing help — press any key to dismiss");
55
+ host.setMessage(" Showing help — ↑↓ to scroll, any other key to dismiss");
34
56
  return;
35
57
  }
36
58
  if (command === "projects") {
@@ -575,7 +597,13 @@ export function getListItems(phrenPath, profile, state, healthLineCount) {
575
597
  case "Skills": {
576
598
  if (!state.project)
577
599
  return [];
578
- const allSkills = getProjectSkills(phrenPath, state.project).map((s) => ({ name: s.name, text: `${s.enabled ? "enabled" : "disabled"} · ${s.path}` }));
600
+ const allSkills = getProjectSkills(phrenPath, state.project).map((s) => ({
601
+ name: s.name,
602
+ text: `${s.enabled ? "enabled" : "disabled"} · ${s.path}`,
603
+ path: s.path,
604
+ scopeType: s.scopeType,
605
+ storePath: s.storePath,
606
+ }));
579
607
  return state.filter
580
608
  ? allSkills.filter((s) => `${s.name} ${s.text}`.toLowerCase().includes(state.filter.toLowerCase()))
581
609
  : allSkills;
@@ -650,6 +678,24 @@ async function doViewAction(host, key) {
650
678
  const cursor = host.currentCursor();
651
679
  const items = host.getListItems();
652
680
  const item = items[cursor];
681
+ // `e` hands the file to the user's own editor, whatever that is.
682
+ if (key === "e") {
683
+ const target = editTargetFor(host, item);
684
+ if (!target) {
685
+ host.setMessage(` ${style.dim("nothing to edit here")}`);
686
+ return;
687
+ }
688
+ const handed = await host.suspend(() => {
689
+ const result = openInEditor(target.path);
690
+ host.setMessage(result.ok
691
+ ? ` ${style.green("✓")} ${target.label}`
692
+ : ` Editor "${result.command}" failed — ${result.error ?? "could not start"}. Set $EDITOR.`);
693
+ });
694
+ if (!handed)
695
+ host.setMessage(` ${style.dim("edit it at")} ${target.path}`);
696
+ host.invalidateSubsectionsCache();
697
+ return;
698
+ }
653
699
  const project = host.state.project;
654
700
  switch (host.state.view) {
655
701
  case "Tasks":
@@ -698,10 +744,14 @@ async function doViewAction(host, key) {
698
744
  host.setMessage("Select a project first.");
699
745
  return;
700
746
  }
701
- const skillPath = item.text;
747
+ const skillPath = item.path;
748
+ if (!skillPath) {
749
+ host.setMessage(" Could not resolve that skill's path.");
750
+ return;
751
+ }
702
752
  host.confirmThen(`Remove skill "${item.name}"?`, () => {
703
753
  try {
704
- removeSkillPath(skillPath.split("·").slice(-1)[0].trim());
754
+ removeSkillPath(skillPath);
705
755
  host.setMessage(` Removed ${item.name}`);
706
756
  host.setCursor(Math.max(0, cursor - 1));
707
757
  }
@@ -716,7 +766,10 @@ async function doViewAction(host, key) {
716
766
  return;
717
767
  }
718
768
  const isEnabled = !item.text?.startsWith("disabled");
719
- setSkillEnabledAndSync(host.phrenPath, project, item.name, !isEnabled);
769
+ // A global skill's enabled flag is recorded under the "global" scope;
770
+ // passing the project wrote a key that nothing ever reads back.
771
+ const scope = item.scopeType === "global" ? "global" : project;
772
+ setSkillEnabledAndSync(item.storePath ?? host.phrenPath, scope, item.name, !isEnabled);
720
773
  host.setMessage(` ${!isEnabled ? "Enabled" : "Disabled"} ${item.name}`);
721
774
  }
722
775
  else if (key === "a") {
@@ -807,9 +860,11 @@ export function applyViewShortcut(host, key) {
807
860
  host.setMessage(` ${TAB_ICONS.Health} Health ${style.dim("(esc to return)")}`);
808
861
  return true;
809
862
  }
863
+ // No message: the bottom bar already says this, and in the Graph view a
864
+ // spare row is worth more than a reminder.
810
865
  if (key === "g") {
811
866
  host.setView("Graph");
812
- host.setMessage(` ${TAB_ICONS.Graph} Graph ${style.dim("↑↓←→ walk · / search · esc back")}`);
867
+ host.setMessage("");
813
868
  return true;
814
869
  }
815
870
  return false;
@@ -890,7 +945,7 @@ export async function handleNavigateKey(host, rawKey) {
890
945
  }
891
946
  if (key === "?") {
892
947
  host.showHelp = !host.showHelp;
893
- host.setMessage(host.showHelp ? " Showing help — press any key to dismiss" : ` ${style.boldCyan("←→")} ${style.dim("tabs")} ${style.boldCyan("↑↓")} ${style.dim("move")} ${style.boldCyan("↵")} ${style.dim("activate")} ${style.boldCyan("?")} ${style.dim("help")}`);
948
+ host.setMessage(host.showHelp ? " Showing help — ↑↓ to scroll, any other key to dismiss" : ` ${style.boldCyan("←→")} ${style.dim("tabs")} ${style.boldCyan("↑↓")} ${style.dim("move")} ${style.boldCyan("↵")} ${style.dim("activate")} ${style.boldCyan("?")} ${style.dim("help")}`);
894
949
  return true;
895
950
  }
896
951
  if (key === "/") {
@@ -929,6 +984,20 @@ export async function handleNavigateKey(host, rawKey) {
929
984
  host.setMessage(` Intro mode: ${style.boldCyan(next)}`);
930
985
  return true;
931
986
  }
987
+ if (key === "E") {
988
+ const items = host.getListItems();
989
+ const item = items[host.currentCursor()];
990
+ const target = editTargetFor(host, item);
991
+ if (!target) {
992
+ host.setMessage(` ${style.dim("nothing to edit here")}`);
993
+ return true;
994
+ }
995
+ const scope = target.kind === "skill" ? (item?.scopeType === "global" ? "global" : host.state.project) : undefined;
996
+ if (host.openEditor(target.path, target.label, target.kind, scope)) {
997
+ host.setMessage(` ${style.dim("i insert · :w write · :q quit")}`);
998
+ }
999
+ return true;
1000
+ }
932
1001
  if (["a", "d", "e", "t", "\x7f"].includes(key)) {
933
1002
  await doViewAction(host, key);
934
1003
  return true;
@@ -30,6 +30,7 @@ export async function renderMenuFrame(phrenPath, profile, state) {
30
30
  "", // no inputCtx
31
31
  "", // no inputBuf
32
32
  false, // no help
33
+ 0, // help scroll (unused: no help)
33
34
  "Tab: Chat ←→: Views ↑↓: Navigate Enter: Select /: Filter Esc: Back", stubDoctor, null, // subsectionsCache
34
35
  () => { }, // setHealthLineCount
35
36
  () => { });
@@ -246,11 +246,21 @@ export function shellHelpText() {
246
246
  ` ${k("/")} ${d("filter")} ${k(":")} ${d("command palette")} ${k("Esc")} ${d("cancel / clear filter")} ${k("?")} ${d("toggle this help")}`,
247
247
  "",
248
248
  hdr("View-specific keys"),
249
- ` ${style.bold("Projects")} ${k("↵")} ${d("open project tasks")} ${k("i")} ${d("cycle intro mode")}`,
249
+ ` ${style.bold("Projects")} ${k("↵")} ${d("open project tasks")} ${k("e")}${d("/")}${k("E")} ${d("edit CLAUDE.md")} ${k("i")} ${d("cycle intro mode")}`,
250
250
  ` ${style.bold("Tasks")} ${k("a")} ${d("add task")} ${k("d")} ${d("toggle active/queue")} ${k("↵")} ${d("mark complete")}`,
251
251
  ` ${style.bold("Findings")} ${k("a")} ${d("tell phren")} ${k("d")} ${d("delete selected")}`,
252
252
  ` ${style.bold("Review Queue")} ${k("↵")} ${d("inspect selected item")} ${d("(read-only)")}`,
253
- ` ${style.bold("Skills")} ${k("t")} ${d("toggle enabled")} ${k("d")} ${d("remove")}`,
253
+ ` ${style.bold("Graph")} ${k("↑↓←→")} ${d("walk")} ${k("1-9")} ${d("neighbour")} ${k("↵")} ${d("select / focus")} ${k("w")} ${d("watch")}`,
254
+ ` ${" ".repeat(13)}${k("/")} ${d("search")} ${k("n N")} ${d("next / prev hit")} ${k("f")} ${d("filter")} ${k("[ ]")} ${d("project")}`,
255
+ ` ${" ".repeat(13)}${k("+ -")} ${d("zoom")} ${k("0")} ${d("fit")} ${k("r")} ${d("re-lay out")} ${k("⇧↑↓←→")} ${d("pan")} ${k("o")} ${d("3D viewer")}`,
256
+ ` ${style.bold("Skills")} ${k("e")} ${d("edit in $EDITOR")} ${k("E")} ${d("edit here")} ${k("t")} ${d("toggle enabled")} ${k("d")} ${d("remove")}`,
257
+ "",
258
+ "",
259
+ hdr("Editor (E, or e for $EDITOR)"),
260
+ ` ${k("h j k l")} ${d("move")} ${k("w b")} ${d("word")} ${k("0 $")} ${d("line")} ${k("gg G")} ${d("file")}`,
261
+ ` ${k("i a I A")} ${d("insert")} ${k("o O")} ${d("open line")} ${k("x")} ${d("delete char")} ${k("dd")} ${d("delete line")}`,
262
+ ` ${k("yy")} ${d("yank")} ${k("p P")} ${d("paste")} ${k("u")} ${d("undo")} ${k("/")} ${d("search")} ${k("n N")} ${d("next / prev")}`,
263
+ ` ${k(":w")} ${d("write")} ${k(":q")} ${d("quit")} ${k(":wq")} ${d("write and quit")} ${k(":q!")} ${d("discard")}`,
254
264
  "",
255
265
  hdr("Palette commands (:cmd)"),
256
266
  ` ${cmd(":open <project>")} ${d("set active project context")}`,
@@ -2,6 +2,8 @@ import { type ShellView, type ShellDeps, type DoctorResultLike } from "./types.j
2
2
  export type { ShellView, ShellDeps } from "./types.js";
3
3
  import type { ShellStartup } from "./startup.js";
4
4
  import { GraphController } from "./graph/controller.js";
5
+ import { type EditorState } from "../editor/buffer.js";
6
+ import { type EditKind } from "../editor/save.js";
5
7
  export declare class PhrenShell {
6
8
  readonly phrenPath: string;
7
9
  readonly profile: string;
@@ -17,16 +19,22 @@ export declare class PhrenShell {
17
19
  private pendingConfirm?;
18
20
  private undoStack;
19
21
  private navMode;
22
+ private editor?;
20
23
  private inputBuf;
21
24
  private inputCtx;
22
25
  inputMqId: string;
23
26
  private cursorMap;
24
27
  private viewScrollMap;
25
28
  private healthLineCount;
29
+ private helpScroll;
26
30
  private _subsectionsCache;
27
31
  private _graph?;
28
32
  private repaintHandler;
29
- get mode(): "navigate" | "input";
33
+ private suspendHandler;
34
+ /** `--live` / `--no-live`; undefined leaves watch mode at its default. */
35
+ private graphLive?;
36
+ get mode(): "navigate" | "input" | "editor";
37
+ get editorState(): EditorState | undefined;
30
38
  get inputBuffer(): string;
31
39
  get filter(): string | undefined;
32
40
  constructor(phrenPath: string, profile: string, deps?: ShellDeps, startup?: ShellStartup);
@@ -38,6 +46,14 @@ export declare class PhrenShell {
38
46
  * to show a build that finished while nothing was typed.
39
47
  */
40
48
  setRepaintHandler(handler: (() => void) | null): void;
49
+ /**
50
+ * Let the host lend the terminal to a child process. Without one — a non-TTY
51
+ * host, or an embedder — callers fall back to telling the user the path.
52
+ */
53
+ setSuspendHandler(handler: ((run: () => Promise<void> | void) => Promise<void>) | null): void;
54
+ get canSuspend(): boolean;
55
+ /** Run `fn` with the terminal released. Resolves false when that is impossible. */
56
+ suspend(fn: () => Promise<void> | void): Promise<boolean>;
41
57
  graph(): GraphController;
42
58
  confirmThen(label: string, action: () => void): void;
43
59
  setView(view: ShellView): void;
@@ -56,10 +72,18 @@ export declare class PhrenShell {
56
72
  name?: string;
57
73
  text?: string;
58
74
  line?: string;
75
+ path?: string;
76
+ scopeType?: string;
77
+ storePath?: string;
59
78
  }[];
60
79
  startInput(ctx: string, initial: string): void;
61
80
  private cancelInput;
62
81
  private submitInput;
82
+ /** Open a file in the built-in editor. Returns false if it cannot be read. */
83
+ openEditor(filePath: string, label: string, kind: EditKind, scope?: string): boolean;
84
+ private closeEditor;
85
+ private saveEditor;
86
+ private handleEditorKey;
63
87
  handleRawKey(key: string): Promise<boolean>;
64
88
  private handleInputKey;
65
89
  private doctorSnapshot;