rolexjs 1.5.0 → 1.6.0

package/dist/index.js

@@ -1,8 +1,332 @@
 // src/index.ts
 export * from "@rolexjs/core";
 
+// src/context.ts
+var RoleContext = class {
+  roleId;
+  focusedGoalId = null;
+  focusedPlanId = null;
+  encounterIds = /* @__PURE__ */ new Set();
+  experienceIds = /* @__PURE__ */ new Set();
+  constructor(roleId) {
+    this.roleId = roleId;
+  }
+  // ================================================================
+  //  Requirements — throw if missing
+  // ================================================================
+  requireGoalId() {
+    if (!this.focusedGoalId) throw new Error("No focused goal. Call want first.");
+    return this.focusedGoalId;
+  }
+  requirePlanId() {
+    if (!this.focusedPlanId) throw new Error("No focused plan. Call plan first.");
+    return this.focusedPlanId;
+  }
+  // ================================================================
+  //  Cognition registries
+  // ================================================================
+  addEncounter(id) {
+    this.encounterIds.add(id);
+  }
+  requireEncounterIds(ids) {
+    for (const id of ids) {
+      if (!this.encounterIds.has(id)) throw new Error(`Encounter not found: "${id}"`);
+    }
+  }
+  consumeEncounters(ids) {
+    for (const id of ids) {
+      this.encounterIds.delete(id);
+    }
+  }
+  addExperience(id) {
+    this.experienceIds.add(id);
+  }
+  requireExperienceIds(ids) {
+    for (const id of ids) {
+      if (!this.experienceIds.has(id)) throw new Error(`Experience not found: "${id}"`);
+    }
+  }
+  consumeExperiences(ids) {
+    for (const id of ids) {
+      this.experienceIds.delete(id);
+    }
+  }
+  // ================================================================
+  //  Rehydration — rebuild from activation state
+  // ================================================================
+  /** Walk the state tree and populate registries. */
+  rehydrate(state) {
+    this.walk(state);
+  }
+  walk(node) {
+    if (node.id) {
+      switch (node.name) {
+        case "goal":
+          if (!this.focusedGoalId) this.focusedGoalId = node.id;
+          break;
+        case "encounter":
+          this.encounterIds.add(node.id);
+          break;
+        case "experience":
+          this.experienceIds.add(node.id);
+          break;
+      }
+    }
+    for (const child of node.children ?? []) {
+      this.walk(child);
+    }
+  }
+  // ================================================================
+  //  Cognitive hints — state-aware AI self-direction cues
+  // ================================================================
+  /** First-person, state-aware hint for the AI after an operation. */
+  cognitiveHint(process) {
+    switch (process) {
+      case "activate":
+        if (!this.focusedGoalId)
+          return "I have no goal yet. I should call `want` to declare one, or `focus` to review existing goals.";
+        return "I have an active goal. I should call `focus` to review progress, or `want` to declare a new goal.";
+      case "focus":
+        if (!this.focusedPlanId)
+          return "I have a goal but no focused plan. I should call `plan` to create or focus on one.";
+        return "I have a plan. I should call `todo` to create tasks, or continue working.";
+      case "want":
+        return "Goal declared. I should call `plan` to design how to achieve it.";
+      case "plan":
+        return "Plan created. I should call `todo` to create concrete tasks.";
+      case "todo":
+        return "Task created. I can add more with `todo`, or start working and call `finish` when done.";
+      case "finish": {
+        const encCount = this.encounterIds.size;
+        if (encCount > 0 && !this.focusedGoalId)
+          return `Task finished. No more goals \u2014 I have ${encCount} encounter(s) to choose from for \`reflect\`, or \`want\` a new goal.`;
+        return "Task finished. I should continue with remaining tasks, or call `complete` when the plan is done.";
+      }
+      case "complete":
+      case "abandon": {
+        const encCount = this.encounterIds.size;
+        const goalNote = this.focusedGoalId ? ` I should check if goal "${this.focusedGoalId}" needs a new \`plan\`, or \`forget\` it if the direction is fulfilled.` : "";
+        if (encCount > 0)
+          return `Plan closed.${goalNote} I have ${encCount} encounter(s) to choose from for \`reflect\`, or I can continue with other plans.`;
+        return `Plan closed.${goalNote} I can create a new \`plan\`, or \`focus\` on another goal.`;
+      }
+      case "reflect": {
+        const expCount = this.experienceIds.size;
+        if (expCount > 0)
+          return `Experience gained. I can \`realize\` principles or \`master\` procedures \u2014 ${expCount} experience(s) available.`;
+        return "Experience gained. I can `realize` a principle, `master` a procedure, or continue working.";
+      }
+      case "realize":
+        return "Principle added. I should continue working.";
+      case "master":
+        return "Procedure added. I should continue working.";
+      default:
+        return null;
+    }
+  }
+};
+
+// src/feature.ts
+import { parse as parseGherkin } from "@rolexjs/parser";
+function parse(source) {
+  const doc = parseGherkin(source);
+  const f = doc.feature;
+  if (!f) throw new Error("No Feature found in source");
+  return {
+    name: f.name,
+    ...f.description?.trim() ? { description: f.description.trim() } : {},
+    ...f.tags?.length ? { tags: f.tags.map((t) => t.name) } : {},
+    scenarios: (f.children ?? []).filter((c) => c.scenario).map((c) => {
+      const s = c.scenario;
+      return {
+        name: s.name,
+        ...s.description?.trim() ? { description: s.description.trim() } : {},
+        ...s.tags?.length ? { tags: s.tags.map((t) => t.name) } : {},
+        steps: (s.steps ?? []).map((st) => ({
+          keyword: st.keyword,
+          text: st.text,
+          ...st.dataTable ? {
+            dataTable: st.dataTable.rows.map((r) => ({
+              cells: r.cells.map((c2) => c2.value)
+            }))
+          } : {}
+        }))
+      };
+    })
+  };
+}
+function serialize(feature) {
+  const lines = [];
+  if (feature.tags?.length) {
+    lines.push(feature.tags.join(" "));
+  }
+  lines.push(`Feature: ${feature.name}`);
+  if (feature.description) {
+    for (const line of feature.description.split("\n")) {
+      lines.push(`  ${line}`);
+    }
+  }
+  for (const scenario of feature.scenarios) {
+    lines.push("");
+    if (scenario.tags?.length) {
+      lines.push(`  ${scenario.tags.join(" ")}`);
+    }
+    lines.push(`  Scenario: ${scenario.name}`);
+    if (scenario.description) {
+      for (const line of scenario.description.split("\n")) {
+        lines.push(`    ${line}`);
+      }
+    }
+    for (const step of scenario.steps) {
+      lines.push(`    ${step.keyword}${step.text}`);
+      if (step.dataTable) {
+        for (const row of step.dataTable) {
+          lines.push(`      | ${row.cells.join(" | ")} |`);
+        }
+      }
+    }
+  }
+  return `${lines.join("\n")}
+`;
+}
+
+// src/find.ts
+var PRIORITY = {
+  individual: 0,
+  organization: 0,
+  position: 0,
+  goal: 1,
+  plan: 2,
+  task: 2,
+  procedure: 3,
+  principle: 3,
+  encounter: 4,
+  experience: 4,
+  identity: 5,
+  charter: 5,
+  duty: 6,
+  requirement: 6,
+  background: 6,
+  tone: 6,
+  mindset: 6
+};
+function priorityOf(name) {
+  return PRIORITY[name] ?? 7;
+}
+function matches(node, target) {
+  if (node.id?.toLowerCase() === target) return true;
+  if (node.alias) {
+    for (const a of node.alias) {
+      if (a.toLowerCase() === target) return true;
+    }
+  }
+  return false;
+}
+function findInState(state, target) {
+  const lowered = target.toLowerCase();
+  let best = null;
+  let bestPriority = Infinity;
+  function walk(node) {
+    if (matches(node, lowered)) {
+      const p = priorityOf(node.name);
+      if (p < bestPriority) {
+        best = node;
+        bestPriority = p;
+        if (p === 0) return;
+      }
+    }
+    for (const child of node.children ?? []) {
+      walk(child);
+      if (bestPriority === 0) return;
+    }
+  }
+  walk(state);
+  return best;
+}
+
+// src/issue-render.ts
+function renderIssue(issue, labelNames) {
+  const lines = [];
+  lines.push(`#${issue.number} ${issue.title} [${issue.status}]`);
+  const meta = [`Author: ${issue.author}`];
+  if (issue.assignee) meta.push(`Assignee: ${issue.assignee}`);
+  if (labelNames && labelNames.length > 0) {
+    meta.push(`Labels: ${labelNames.join(", ")}`);
+  }
+  lines.push(meta.join(" | "));
+  if (issue.body) {
+    lines.push("\u2500\u2500\u2500");
+    lines.push(issue.body);
+  }
+  return lines.join("\n");
+}
+function renderIssueList(issues) {
+  if (issues.length === 0) return "No issues found.";
+  const lines = [];
+  for (const issue of issues) {
+    const assignee = issue.assignee ? ` \u2192 ${issue.assignee}` : "";
+    lines.push(`#${issue.number}  [${issue.status}]  ${issue.title}  (${issue.author}${assignee})`);
+  }
+  return lines.join("\n");
+}
+function renderComment(comment) {
+  const time = formatTime(comment.createdAt);
+  return `${comment.author} (${time}):
+${comment.body}`;
+}
+function renderCommentList(comments) {
+  if (comments.length === 0) return "No comments.";
+  return comments.map(renderComment).join("\n\u2500\u2500\u2500\n");
+}
+var statusTemplates = {
+  publish: (i) => `Issue #${i.number} created.`,
+  close: (i) => `Issue #${i.number} closed.`,
+  reopen: (i) => `Issue #${i.number} reopened.`,
+  update: (i) => `Issue #${i.number} updated.`,
+  assign: (i) => `Issue #${i.number} assigned to ${i.assignee ?? "nobody"}.`,
+  comment: (i) => `Comment added to #${i.number}.`,
+  label: (i) => `Label added to #${i.number}.`,
+  unlabel: (i) => `Label removed from #${i.number}.`
+};
+async function renderIssueResult(action, result, resolveLabels) {
+  switch (action) {
+    case "list":
+      return renderIssueList(result);
+    case "comments":
+      return renderCommentList(result);
+    case "comment": {
+      const comment = result;
+      return `Comment added to issue.
+
+${renderComment(comment)}`;
+    }
+    case "get": {
+      if (!result) return "Issue not found.";
+      const issue = result;
+      const labelNames = await resolveLabelNames(issue, resolveLabels);
+      return renderIssue(issue, labelNames);
+    }
+    default: {
+      const issue = result;
+      const labelNames = await resolveLabelNames(issue, resolveLabels);
+      const status = statusTemplates[action]?.(issue) ?? `Issue #${issue.number} ${action}.`;
+      return `${status}
+
+${renderIssue(issue, labelNames)}`;
+    }
+  }
+}
+function formatTime(iso) {
+  return iso.replace("T", " ").replace(/\.\d+Z$/, "");
+}
+async function resolveLabelNames(issue, resolveLabels) {
+  if (!issue.labels || issue.labels.length === 0) return void 0;
+  if (!resolveLabels) return void 0;
+  return resolveLabels(issue.labels);
+}
+
 // src/render.ts
-import { directives, processes, world } from "@rolexjs/core";
+import { directives, processes, world } from "@rolexjs/prototype";
 var descriptions = {
   // Lifecycle
   born: (n) => `Individual "${n}" is born.`,
@@ -30,20 +354,6 @@ var descriptions = {
   deliver: (n) => `Deliverable "${n}" added.`,
   wiki: (n) => `Wiki entry "${n}" added.`,
   archive: (n) => `Project "${n}" archived.`,
-  produce: (n) => `Product "${n}" produced.`,
-  // Product
-  strategy: (n) => `Strategy defined for "${n}".`,
-  spec: (n) => `Spec "${n}" added.`,
-  release: (n) => `Release "${n}" published.`,
-  channel: (n) => `Channel "${n}" added.`,
-  own: (n) => `Owner assigned to "${n}".`,
-  disown: (n) => `Owner removed from "${n}".`,
-  deprecate: (n) => `Product "${n}" deprecated.`,
-  // Society
-  crown: (n) => `"${n}" crowned \u2014 sovereign permissions granted.`,
-  uncrown: (n) => `"${n}" uncrowned \u2014 sovereign permissions revoked.`,
-  // Top-level perception
-  inspect: (n) => `Inspecting "${n}".`,
   // Role
   activate: (n) => `Role "${n}" activated.`,
   focus: (n) => `Focused on goal "${n}".`,
@@ -92,20 +402,6 @@ var hints = {
   deliver: "deliverable recorded.",
   wiki: "knowledge entry recorded.",
   archive: "the project is archived.",
-  produce: "define strategy, add specs, or assign an owner.",
-  // Product
-  strategy: "add behavior specs (BDD contracts) for the product.",
-  spec: "add more specs, or publish a release.",
-  release: "add distribution channels, or continue adding specs.",
-  channel: "distribution channel recorded.",
-  own: "the individual is now the product owner.",
-  disown: "the individual is no longer the product owner.",
-  deprecate: "the product is deprecated.",
-  // Society
-  crown: "the individual now has sovereign permissions over society.",
-  uncrown: "the individual no longer has sovereign permissions.",
-  // Top-level perception
-  inspect: "use inspect on child nodes for deeper detail, or activate to work as a role.",
   // Role
   activate: "want a goal, or check the current state.",
   focus: "plan how to work toward it, or add tasks.",
@@ -127,13 +423,19 @@ function hint(process) {
   const h = hints[process];
   return h ? `Next: ${h}` : "What would you like to do next?";
 }
+function detail(process) {
+  return processes[process] ?? "";
+}
+function directive(topic, scenario) {
+  return directives[topic]?.[scenario] ?? "";
+}
 function renderState(state, depth = 1, options) {
   const lines = [];
   const level = Math.min(depth, 6);
   const heading = "#".repeat(level);
   const idPart = state.id ? ` (${state.id})` : "";
   const originPart = state.origin ? ` {${state.origin}}` : "";
-  const tagPart = state.tags?.length ? ` ${state.tags.map((t) => `#${t}`).join(" ")}` : "";
+  const tagPart = state.tag ? ` #${state.tag}` : "";
   const progressPart = state.name === "goal" ? goalProgress(state) : "";
   lines.push(`${heading} [${state.name}]${idPart}${originPart}${tagPart}${progressPart}`);
   if (options?.fold?.(state)) {
@@ -145,12 +447,11 @@ function renderState(state, depth = 1, options) {
   }
   if (state.links && state.links.length > 0) {
     const compactRelations = /* @__PURE__ */ new Set(["after", "before", "fallback", "fallback-for"]);
-    const allCompact = options?.compactLinks;
-    const compact = allCompact ? state.links : state.links.filter((l) => compactRelations.has(l.relation));
-    const expanded = allCompact ? [] : state.links.filter((l) => !compactRelations.has(l.relation));
+    const compact = state.links.filter((l) => compactRelations.has(l.relation));
+    const expanded = state.links.filter((l) => !compactRelations.has(l.relation));
     for (const link of compact) {
       const targetId = link.target.id ? ` (${link.target.id})` : "";
-      const targetTag = link.target.tags?.length ? ` ${link.target.tags.map((t) => `#${t}`).join(" ")}` : "";
+      const targetTag = link.target.tag ? ` #${link.target.tag}` : "";
       lines.push(`> ${link.relation}: [${link.target.name}]${targetId}${targetTag}`);
     }
     if (expanded.length > 0) {
@@ -170,41 +471,6 @@ function renderState(state, depth = 1, options) {
   }
   return lines.join("\n");
 }
-function collectPermissions(state) {
-  const seen = /* @__PURE__ */ new Set();
-  const result = [];
-  const walk = (s) => {
-    if (s.links) {
-      for (const link of s.links) {
-        if (link.permissions) {
-          for (const p of link.permissions) {
-            if (!seen.has(p.command)) {
-              seen.add(p.command);
-              result.push(p);
-            }
-          }
-        }
-      }
-    }
-    if (s.children) {
-      for (const child of s.children) {
-        walk(child);
-      }
-    }
-  };
-  walk(state);
-  return result;
-}
-function renderPermissions(permissions) {
-  if (permissions.length === 0) return "";
-  const lines = [];
-  lines.push("# Permissions\n");
-  for (const p of permissions) {
-    lines.push(p.content);
-    lines.push("");
-  }
-  return lines.join("\n");
-}
 var CONCEPT_ORDER = [
   // Individual — Identity
   "identity",
@@ -230,12 +496,7 @@ var CONCEPT_ORDER = [
   "scope",
   "milestone",
   "deliverable",
-  "wiki",
-  // Product
-  "strategy",
-  "spec",
-  "release",
-  "channel"
+  "wiki"
 ];
 function goalProgress(goal) {
   let plans = 0;
@@ -245,10 +506,10 @@ function goalProgress(goal) {
   function walk(node) {
     if (node.name === "plan") {
       plans++;
-      if (node.tags?.includes("done") || node.tags?.includes("abandoned")) plansDone++;
+      if (node.tag === "done" || node.tag === "abandoned") plansDone++;
     } else if (node.name === "task") {
       tasks++;
-      if (node.tags?.includes("done")) tasksDone++;
+      if (node.tag === "done") tasksDone++;
     }
     for (const child of node.children ?? []) walk(child);
   }
@@ -271,92 +532,25 @@ function sortByConceptOrder(children) {
     return aOrder - bOrder;
   });
 }
-
-// src/product-render.ts
-function renderProduct(state) {
-  const lines = [];
-  const id = state.id ?? "(no id)";
-  const tagPart = state.tags?.length ? ` ${state.tags.map((t) => `#${t}`).join(" ")}` : "";
-  lines.push(`# ${id}${tagPart}`);
-  if (state.information) {
-    lines.push("");
-    lines.push(state.information);
-  }
-  const owners = state.links?.filter((l) => l.relation === "ownership") ?? [];
-  if (owners.length > 0) {
-    lines.push("");
-    lines.push("## Owner");
-    for (const o of owners) {
-      const alias = Array.isArray(o.target.alias) && o.target.alias.length ? ` (${o.target.alias.join(", ")})` : "";
-      lines.push(`- ${o.target.id ?? "(no id)"}${alias}`);
-    }
-  }
-  const children = state.children ?? [];
-  const strategies = children.filter((c) => c.name === "strategy");
-  const specs = children.filter((c) => c.name === "spec");
-  const releases = children.filter((c) => c.name === "release");
-  const channels = children.filter((c) => c.name === "channel");
-  if (strategies.length > 0) {
-    lines.push("");
-    lines.push("## Strategy");
-    for (const s of strategies) {
-      if (s.information) lines.push(s.information);
-    }
-  }
-  if (specs.length > 0) {
-    lines.push("");
-    lines.push("## Specs");
-    for (const s of specs) {
-      const title = s.id ?? extractFeatureTitle(s.information);
-      lines.push(`- ${title}`);
-    }
-  }
-  if (releases.length > 0) {
-    lines.push("");
-    lines.push("## Releases");
-    for (const r of releases) {
-      const rTag = r.tags?.length ? ` ${r.tags.map((t) => `#${t}`).join(" ")}` : "";
-      const title = r.id ?? extractFeatureTitle(r.information);
-      lines.push(`- ${title}${rTag}`);
-    }
-  }
-  if (channels.length > 0) {
-    lines.push("");
-    lines.push("## Channels");
-    for (const c of channels) {
-      const title = c.id ?? extractFeatureTitle(c.information);
-      lines.push(`- ${title}`);
-    }
-  }
-  return lines.join("\n");
-}
-function renderProductResult(action, state) {
-  const name = state.id ?? state.name;
+function render(opts) {
+  const { process, name, state, cognitiveHint, fold } = opts;
   const lines = [];
-  lines.push(describe(action, name, state));
-  lines.push(hint(action));
-  const productState = isProductNode(state) ? state : null;
-  if (productState) {
-    lines.push("");
-    lines.push(renderProduct(productState));
+  lines.push(describe(process, name, state));
+  lines.push(hint(process));
+  if (cognitiveHint) {
+    lines.push(`I \u2192 ${cognitiveHint}`);
   }
+  lines.push("");
+  lines.push(renderState(state, 1, fold ? { fold } : void 0));
   return lines.join("\n");
 }
-function isProductNode(state) {
-  return state.name === "product";
-}
-function extractFeatureTitle(information) {
-  if (!information) return "(untitled)";
-  const match = information.match(/^Feature:\s*(.+)$/m);
-  return match?.[1]?.trim() ?? information.split("\n")[0].trim();
-}
 
 // src/project-render.ts
 function renderProject(state) {
   const lines = [];
   const id = state.id ?? "(no id)";
-  const tagPart = state.tags?.length ? ` ${state.tags.map((t) => `#${t}`).join(" ")}` : "";
-  lines.push(`# ${id}${tagPart}`);
+  const tag = state.tag ? ` #${state.tag}` : "";
+  lines.push(`# ${id}${tag}`);
   if (state.information) {
     lines.push("");
     lines.push(state.information);
@@ -366,7 +560,7 @@ function renderProject(state) {
     lines.push("");
     lines.push("## Members");
     for (const m of members) {
-      const alias = Array.isArray(m.target.alias) && m.target.alias.length ? ` (${m.target.alias.join(", ")})` : "";
+      const alias = m.target.alias?.length ? ` (${m.target.alias.join(", ")})` : "";
       lines.push(`- ${m.target.id ?? "(no id)"}${alias}`);
     }
   }
@@ -386,12 +580,12 @@ function renderProject(state) {
     lines.push("");
     lines.push("## Milestones");
     for (const m of milestones) {
-      const mTag = m.tags?.length ? ` ${m.tags.map((t) => `#${t}`).join(" ")}` : "";
-      const marker = m.tags?.includes("done") ? "[x]" : "[ ]";
-      const title = extractFeatureTitle2(m.information);
-      lines.push(`- ${marker} ${m.id ?? title}${mTag}`);
+      const tag2 = m.tag ? ` #${m.tag}` : "";
+      const marker = m.tag === "done" ? "[x]" : "[ ]";
+      const title = extractFeatureTitle(m.information);
+      lines.push(`- ${marker} ${m.id ?? title}${tag2}`);
       if (m.information && m.id) {
-        const desc = extractFeatureTitle2(m.information);
+        const desc = extractFeatureTitle(m.information);
         if (desc && desc !== m.id) lines.push(`  ${desc}`);
       }
     }
@@ -400,7 +594,7 @@ function renderProject(state) {
     lines.push("");
     lines.push("## Deliverables");
     for (const d of deliverables) {
-      const title = d.id ?? extractFeatureTitle2(d.information);
+      const title = d.id ?? extractFeatureTitle(d.information);
       lines.push(`- ${title}`);
     }
   }
@@ -408,7 +602,7 @@ function renderProject(state) {
     lines.push("");
     lines.push("## Wiki");
     for (const w of wikis) {
-      const title = w.id ?? extractFeatureTitle2(w.information);
+      const title = w.id ?? extractFeatureTitle(w.information);
       lines.push(`- ${title}`);
     }
   }
@@ -429,207 +623,361 @@ function renderProjectResult(action, state) {
 function isProjectNode(state) {
   return state.name === "project";
 }
-function extractFeatureTitle2(information) {
+function extractFeatureTitle(information) {
   if (!information) return "(untitled)";
   const match = information.match(/^Feature:\s*(.+)$/m);
   return match?.[1]?.trim() ?? information.split("\n")[0].trim();
 }
 
-// src/rolex.ts
-import { createBuilder } from "@rolexjs/core";
-import { genesis } from "@rolexjs/genesis";
-
-// src/renderers/index.ts
-import { RendererRouter } from "@rolexjs/core";
-
-// src/renderers/inspect.ts
-var InspectRenderer = class {
-  render(_command, result) {
-    const name = result.state.id ?? result.state.name;
-    const lines = [];
-    lines.push(describe(result.process, name, result.state));
-    lines.push(hint(result.process));
-    lines.push("");
-    lines.push(renderState(result.state, 1, { compactLinks: true }));
-    return lines.join("\n");
+// src/role.ts
+var Role = class {
+  roleId;
+  ctx;
+  api;
+  constructor(roleId, ctx, api) {
+    this.roleId = roleId;
+    this.ctx = ctx;
+    this.api = api;
   }
-};
-
-// src/renderers/org.ts
-var OrgRenderer = class {
-  render(command, result) {
-    const process = command.startsWith("org.") ? command.slice("org.".length) : command;
-    const name = result.state.id ?? result.state.name;
-    const lines = [];
-    lines.push(describe(process, name, result.state));
-    lines.push(hint(process));
-    lines.push("");
-    lines.push(renderState(result.state));
-    return lines.join("\n");
+  /** Project the individual's full state tree (used after activate). */
+  async project() {
+    const result = await this.api.ops["role.focus"](this.roleId);
+    const focusedGoalId = this.ctx.focusedGoalId;
+    return this.fmt("activate", this.roleId, result, {
+      fold: (node) => node.name === "goal" && node.id !== focusedGoalId || node.name === "requirement"
+    });
   }
-};
-
-// src/renderers/position.ts
-var PositionRenderer = class {
-  render(command, result) {
-    const process = command.startsWith("position.") ? command.slice("position.".length) : command;
-    const name = result.state.id ?? result.state.name;
-    const lines = [];
-    lines.push(describe(process, name, result.state));
-    lines.push(hint(process));
-    lines.push("");
-    lines.push(renderState(result.state));
-    return lines.join("\n");
+  /** Render an OpResult into a 3-layer output string. */
+  fmt(process, name, result, extra) {
+    return render({
+      process,
+      name,
+      state: result.state,
+      cognitiveHint: this.ctx.cognitiveHint(process) ?? null,
+      fold: extra?.fold
+    });
   }
-};
-
-// src/renderers/product.ts
-var ProductRenderer = class {
-  render(command, result) {
-    const action = command.startsWith("product.") ? command.slice("product.".length) : command;
-    return renderProductResult(action, result.state);
+  async save() {
+    await this.api.saveCtx(this.ctx);
   }
-};
-
-// src/renderers/project.ts
-var ProjectRenderer = class {
-  render(command, result) {
-    const action = command.startsWith("project.") ? command.slice("project.".length) : command;
-    if (action === "produce") {
-      return renderProductResult(action, result.state);
+  // ---- Execution ----
+  /** Focus: view or switch focused goal. Only accepts goal ids. */
+  async focus(goal) {
+    const goalId = goal ?? this.ctx.requireGoalId();
+    const result = await this.api.ops["role.focus"](goalId);
+    if (result.state.name !== "goal") {
+      throw new Error(
+        `"${goalId}" is a ${result.state.name}, not a goal. focus only accepts goal ids.`
+      );
     }
-    return renderProjectResult(action, result.state);
+    const switched = goalId !== this.ctx.focusedGoalId;
+    this.ctx.focusedGoalId = goalId;
+    if (switched) this.ctx.focusedPlanId = null;
+    await this.save();
+    return this.fmt("focus", goalId, result);
   }
-};
-
-// src/renderers/role.ts
-var RoleRenderer = class {
-  render(command, result) {
-    const process = command.startsWith("role.") ? command.slice("role.".length) : command;
-    const name = result.state.id ?? result.state.name;
-    const lines = [];
-    lines.push(describe(process, name, result.state));
-    lines.push(hint(process));
-    lines.push("");
-    lines.push(renderState(result.state));
-    if (process === "activate") {
-      const permissions = collectPermissions(result.state);
-      if (permissions.length > 0) {
-        lines.push("");
-        lines.push(renderPermissions(permissions));
+  /** Want: declare a goal. */
+  async want(goal, id, alias) {
+    const result = await this.api.ops["role.want"](this.roleId, goal, id, alias);
+    if (id) this.ctx.focusedGoalId = id;
+    this.ctx.focusedPlanId = null;
+    await this.save();
+    return this.fmt("want", id ?? this.roleId, result);
+  }
+  /** Plan: create a plan for the focused goal. */
+  async plan(plan, id, after, fallback) {
+    const result = await this.api.ops["role.plan"](
+      this.ctx.requireGoalId(),
+      plan,
+      id,
+      after,
+      fallback
+    );
+    if (id) this.ctx.focusedPlanId = id;
+    await this.save();
+    return this.fmt("plan", id ?? "plan", result);
+  }
+  /** Todo: add a task to the focused plan. */
+  async todo(task, id, alias) {
+    const result = await this.api.ops["role.todo"](this.ctx.requirePlanId(), task, id, alias);
+    return this.fmt("todo", id ?? "task", result);
+  }
+  /** Finish: complete a task, optionally record an encounter. */
+  async finish(task, encounter) {
+    const result = await this.api.ops["role.finish"](task, this.roleId, encounter);
+    if (encounter && result.state.id) {
+      this.ctx.addEncounter(result.state.id);
+    }
+    return this.fmt("finish", task, result);
+  }
+  /** Complete: close a plan as done, record encounter. */
+  async complete(plan, encounter) {
+    const planId = plan ?? this.ctx.requirePlanId();
+    const result = await this.api.ops["role.complete"](planId, this.roleId, encounter);
+    this.ctx.addEncounter(result.state.id ?? planId);
+    if (this.ctx.focusedPlanId === planId) this.ctx.focusedPlanId = null;
+    await this.save();
+    return this.fmt("complete", planId, result);
+  }
+  /** Abandon: drop a plan, record encounter. */
+  async abandon(plan, encounter) {
+    const planId = plan ?? this.ctx.requirePlanId();
+    const result = await this.api.ops["role.abandon"](planId, this.roleId, encounter);
+    this.ctx.addEncounter(result.state.id ?? planId);
+    if (this.ctx.focusedPlanId === planId) this.ctx.focusedPlanId = null;
+    await this.save();
+    return this.fmt("abandon", planId, result);
+  }
+  // ---- Cognition ----
+  /** Reflect: consume encounters → experience. Empty encounters = direct creation. */
+  async reflect(encounters, experience, id) {
+    if (encounters.length > 0) {
+      this.ctx.requireEncounterIds(encounters);
+    }
+    const first = encounters[0];
+    const result = await this.api.ops["role.reflect"](first, this.roleId, experience, id);
+    for (let i = 1; i < encounters.length; i++) {
+      await this.api.ops["role.forget"](encounters[i]);
+    }
+    if (encounters.length > 0) {
+      this.ctx.consumeEncounters(encounters);
+    }
+    if (id) this.ctx.addExperience(id);
+    return this.fmt("reflect", id ?? "experience", result);
+  }
+  /** Realize: consume experiences → principle. Empty experiences = direct creation. */
+  async realize(experiences, principle, id) {
+    if (experiences.length > 0) {
+      this.ctx.requireExperienceIds(experiences);
+    }
+    const first = experiences[0];
+    const result = await this.api.ops["role.realize"](first, this.roleId, principle, id);
+    for (let i = 1; i < experiences.length; i++) {
+      await this.api.ops["role.forget"](experiences[i]);
+    }
+    if (experiences.length > 0) {
+      this.ctx.consumeExperiences(experiences);
+    }
+    return this.fmt("realize", id ?? "principle", result);
+  }
+  /** Master: create procedure, optionally consuming experiences. */
+  async master(procedure, id, experiences) {
+    if (experiences && experiences.length > 0) {
+      this.ctx.requireExperienceIds(experiences);
+    }
+    const first = experiences?.[0];
+    const result = await this.api.ops["role.master"](this.roleId, procedure, id, first);
+    if (experiences) {
+      for (let i = 1; i < experiences.length; i++) {
+        await this.api.ops["role.forget"](experiences[i]);
       }
+      this.ctx.consumeExperiences(experiences);
     }
-    return lines.join("\n");
+    return this.fmt("master", id ?? "procedure", result);
   }
-};
-
-// src/renderers/society.ts
-var SocietyRenderer = class {
-  render(command, result) {
-    const process = command.startsWith("society.") ? command.slice("society.".length) : command;
-    const name = result.state.id ?? result.state.name;
-    const lines = [];
-    lines.push(describe(process, name, result.state));
-    lines.push(hint(process));
-    lines.push("");
-    lines.push(renderState(result.state));
-    return lines.join("\n");
+  // ---- Knowledge management ----
+  /** Forget: remove any node under the individual by id. */
+  async forget(nodeId) {
+    const result = await this.api.ops["role.forget"](nodeId);
+    if (this.ctx.focusedGoalId === nodeId) this.ctx.focusedGoalId = null;
+    if (this.ctx.focusedPlanId === nodeId) this.ctx.focusedPlanId = null;
+    await this.save();
+    return this.fmt("forget", nodeId, result);
+  }
+  // ---- Skills + unified entry ----
+  /** Skill: load full skill content by locator. */
+  async skill(locator) {
+    return await this.api.ops["role.skill"](locator);
+  }
+  /** Use: subjective execution — `!ns.method` or ResourceX locator. */
+  async use(locator, args) {
+    const result = await this.api.direct(locator, args);
+    if (locator.startsWith("!issue.")) {
+      const action = locator.slice("!issue.".length);
+      return await renderIssueResult(action, result, this.api.resolveLabels);
+    }
+    if (locator.startsWith("!project.")) {
+      const action = locator.slice("!project.".length);
+      const opResult = result;
+      return renderProjectResult(action, opResult.state);
+    }
+    return result;
   }
 };
 
-// src/renderers/survey.ts
-var SurveyRenderer = class {
-  render(_command, result) {
-    const children = result.state.children ?? [];
-    if (children.length === 0) {
-      return "Society is empty.";
-    }
-    const types = new Set(children.map((c) => c.name));
-    if (types.size === 1 && !types.has("organization")) {
-      return this.renderFlat(children);
-    }
-    return this.renderTree(children);
-  }
-  renderFlat(items) {
-    const lines = [];
-    for (const item of items) {
-      const tag = item.tags?.length ? ` ${item.tags.map((t) => `#${t}`).join(" ")}` : "";
-      const alias = Array.isArray(item.alias) && item.alias.length ? ` (${item.alias.join(", ")})` : "";
-      lines.push(`${item.id ?? "(no id)"}${alias}${tag}`);
+// src/rolex.ts
+import * as C from "@rolexjs/core";
+import { createOps, directives as directives2, toArgs } from "@rolexjs/prototype";
+import { createIssueX } from "issuexjs";
+import { createResourceX, setProvider } from "resourcexjs";
+var Rolex = class _Rolex {
+  rt;
+  ops;
+  resourcex;
+  issuex;
+  repo;
+  initializer;
+  bootstrap;
+  society;
+  past;
+  constructor(platform) {
+    this.repo = platform.repository;
+    this.rt = this.repo.runtime;
+    this.initializer = platform.initializer;
+    this.bootstrap = platform.bootstrap ?? [];
+    if (platform.resourcexProvider) {
+      setProvider(platform.resourcexProvider);
+      this.resourcex = createResourceX(
+        platform.resourcexExecutor ? { isolator: "custom", executor: platform.resourcexExecutor } : void 0
+      );
+    }
+    if (platform.issuexProvider) {
+      this.issuex = createIssueX({ provider: platform.issuexProvider });
     }
-    return lines.join("\n");
   }
-  renderTree(children) {
-    const orgs = children.filter((c) => c.name === "organization");
-    const individuals = children.filter((c) => c.name === "individual");
-    const individualPositions = /* @__PURE__ */ new Map();
-    for (const ind of individuals) {
-      const serves = ind.links?.filter((l) => l.relation === "serve") ?? [];
-      if (serves.length > 0) {
-        individualPositions.set(
-          ind.id ?? "",
-          serves.map((l) => l.target.id ?? "(no id)")
-        );
-      }
+  /** Create a Rolex instance from a Platform (async due to Runtime initialization). */
+  static async create(platform) {
+    const rolex = new _Rolex(platform);
+    await rolex.init();
+    return rolex;
+  }
+  /** Async initialization — called by Rolex.create(). */
+  async init() {
+    const roots = await this.rt.roots();
+    this.society = roots.find((r) => r.name === "society") ?? await this.rt.create(null, C.society);
+    const societyState = await this.rt.project(this.society);
+    const existingPast = societyState.children?.find((c) => c.name === "past");
+    this.past = existingPast ?? await this.rt.create(this.society, C.past);
+    this.ops = createOps({
+      rt: this.rt,
+      society: this.society,
+      past: this.past,
+      resolve: async (id) => {
+        const node = await this.find(id);
+        if (!node) throw new Error(`"${id}" not found.`);
+        return node;
+      },
+      find: (id) => this.find(id),
+      resourcex: this.resourcex,
+      issuex: this.issuex,
+      prototype: this.repo.prototype,
+      direct: (locator, args) => this.direct(locator, args)
+    });
+  }
+  /** Genesis — create the world on first run. Settles built-in prototypes. */
+  async genesis() {
+    await this.initializer?.bootstrap();
+    for (const source of this.bootstrap) {
+      await this.direct("!prototype.settle", { source });
     }
-    const affiliatedIndividuals = /* @__PURE__ */ new Set();
-    const lines = [];
-    for (const org of orgs) {
-      const alias = Array.isArray(org.alias) && org.alias.length ? ` (${org.alias.join(", ")})` : "";
-      const tag = org.tags?.length ? ` ${org.tags.map((t) => `#${t}`).join(" ")}` : "";
-      lines.push(`${org.id}${alias}${tag}`);
-      const projects = org.links?.filter((l) => l.relation === "project") ?? [];
-      for (const p of projects) {
-        const pAlias = Array.isArray(p.target.alias) && p.target.alias.length ? ` (${p.target.alias.join(", ")})` : "";
-        const pTag = p.target.tags?.length ? ` ${p.target.tags.map((t) => `#${t}`).join(" ")}` : "";
-        lines.push(`  \u{1F4E6} ${p.target.id ?? "(no id)"}${pAlias}${pTag}`);
+  }
+  /**
+   * Activate a role — returns a stateful Role handle.
+   *
+   * If the individual does not exist in runtime but a prototype is registered,
+   * auto-born the individual first.
+   */
+  async activate(individual) {
+    let node = await this.find(individual);
+    if (!node) {
+      const hasProto = Object.hasOwn(this.repo.prototype.list(), individual);
+      if (hasProto) {
+        await this.ops["individual.born"](void 0, individual);
+        node = await this.find(individual);
+      } else {
+        throw new Error(`"${individual}" not found.`);
       }
-      const members = org.links?.filter((l) => l.relation === "membership") ?? [];
-      if (members.length === 0 && projects.length === 0) {
-        lines.push("  (empty)");
+    }
+    const state = await this.rt.project(node);
+    const ctx = new RoleContext(individual);
+    ctx.rehydrate(state);
+    const persisted = await this.repo.loadContext(individual);
+    if (persisted) {
+      if (persisted.focusedGoalId && await this.find(persisted.focusedGoalId)) {
+        ctx.focusedGoalId = persisted.focusedGoalId;
       }
-      for (const m of members) {
-        affiliatedIndividuals.add(m.target.id ?? "");
-        const mAlias = Array.isArray(m.target.alias) && m.target.alias.length ? ` (${m.target.alias.join(", ")})` : "";
-        const mTag = m.target.tags?.length ? ` ${m.target.tags.map((t) => `#${t}`).join(" ")}` : "";
-        const posLabels = individualPositions.get(m.target.id ?? "");
-        const posStr = posLabels?.length ? ` \u2014 ${posLabels.join(", ")}` : "";
-        lines.push(`  ${m.target.id}${mAlias}${mTag}${posStr}`);
+      if (persisted.focusedPlanId && await this.find(persisted.focusedPlanId)) {
+        ctx.focusedPlanId = persisted.focusedPlanId;
       }
-      lines.push("");
     }
-    const unaffiliated = individuals.filter((ind) => !affiliatedIndividuals.has(ind.id ?? ""));
-    if (unaffiliated.length > 0) {
-      lines.push("\u2500\u2500\u2500 unaffiliated \u2500\u2500\u2500");
-      for (const ind of unaffiliated) {
-        const alias = Array.isArray(ind.alias) && ind.alias.length ? ` (${ind.alias.join(", ")})` : "";
-        const tag = ind.tags?.length ? ` ${ind.tags.map((t) => `#${t}`).join(" ")}` : "";
-        const posLabels = individualPositions.get(ind.id ?? "");
-        const posStr = posLabels?.length ? ` \u2014 ${posLabels.join(", ")}` : "";
-        lines.push(`  ${ind.id}${alias}${tag}${posStr}`);
+    const ops = this.ops;
+    const repo = this.repo;
+    const saveCtx = async (c) => {
+      await repo.saveContext(c.roleId, {
+        focusedGoalId: c.focusedGoalId,
+        focusedPlanId: c.focusedPlanId
+      });
+    };
+    const api = {
+      ops,
+      saveCtx,
+      direct: this.direct.bind(this),
+      resolveLabels: this.issuex ? async (ids) => {
+        const names = [];
+        for (const id of ids) {
+          const label = await this.issuex.getLabel(id);
+          if (label) names.push(label.name);
+        }
+        return names;
+      } : void 0
+    };
+    return new Role(individual, ctx, api);
+  }
+  /** Find a node by id or alias across the entire society tree. Internal use only. */
+  async find(id) {
+    const state = await this.rt.project(this.society);
+    return findInState(state, id);
+  }
+  /**
+   * Direct the world to execute an instruction.
+   *
+   * - `!namespace.method` — dispatch to ops
+   * - anything else — delegate to ResourceX `ingest`
+   */
+  async direct(locator, args) {
+    if (locator.startsWith("!")) {
+      const command = locator.slice(1);
+      const fn = this.ops[command];
+      if (!fn) {
+        const hint2 = directives2["identity-ethics"]?.["on-unknown-command"] ?? "";
+        throw new Error(
+          `Unknown command "${locator}".
+
+You may be guessing the command name. Load the relevant skill first with skill(locator) to learn the correct syntax.
+
+` + hint2
+        );
       }
+      return await fn(...toArgs(command, args ?? {}));
     }
-    return lines.join("\n");
+    if (!this.resourcex) throw new Error("ResourceX is not available.");
+    return this.resourcex.ingest(locator, args);
   }
 };
-
-// src/renderers/index.ts
-function createRendererRouter() {
-  return new RendererRouter().register("role", new RoleRenderer()).register("org", new OrgRenderer()).register("position", new PositionRenderer()).register("product", new ProductRenderer()).register("project", new ProjectRenderer()).register("society", new SocietyRenderer()).register("survey", new SurveyRenderer()).register("inspect", new InspectRenderer());
-}
-
-// src/rolex.ts
-function createRoleX(config) {
-  return createBuilder({
-    platform: config.platform,
-    renderer: config.renderer ?? createRendererRouter(),
-    prototypes: [genesis]
-  });
+async function createRoleX(platform) {
+  return Rolex.create(platform);
 }
 export {
+  Role,
+  RoleContext,
+  Rolex,
   createRoleX,
-  renderProduct,
-  renderProductResult,
-  renderProjectResult
+  describe,
+  detail,
+  directive,
+  findInState,
+  hint,
+  parse,
+  render,
+  renderComment,
+  renderCommentList,
+  renderIssue,
+  renderIssueList,
+  renderIssueResult,
+  renderProject,
+  renderProjectResult,
+  renderState,
+  serialize,
+  world
 };
 //# sourceMappingURL=index.js.map