@parall/agent-core 1.14.5 → 1.15.1

package/dist/event-format.js

@@ -3,13 +3,13 @@ export function buildEventBody(event) {
     if (event.type === "message") {
         lines.push(`[Event: message.new]`);
         const chatLabel = event.targetName
-            ? `"${event.targetName}" (${event.targetId})`
-            : event.targetId;
+            ? `"${event.targetName}" (prll://${event.targetId})`
+            : `prll://${event.targetId}`;
         lines.push(`[Chat: ${chatLabel} | type: ${event.targetType ?? "unknown"}]`);
-        lines.push(`[From: ${event.senderName} (${event.senderId})]`);
-        lines.push(`[Message ID: ${event.messageId}]`);
+        lines.push(`[From: ${event.senderName} (prll://${event.senderId})]`);
+        lines.push(`[Message ID: prll://${event.messageId}]`);
         if (event.threadRootId)
-            lines.push(`[Thread: ${event.threadRootId}]`);
+            lines.push(`[Thread: prll://${event.threadRootId}]`);
         if (event.noReply)
             lines.push(`[Hint: no_reply]`);
         if (event.mediaFields?.MediaUrl) {
@@ -20,10 +20,10 @@ export function buildEventBody(event) {
     else {
         lines.push(`[Event: task.assigned]`);
         const taskLabel = event.targetName
-            ? `${event.targetName} (${event.targetId})`
-            : event.targetId;
-        lines.push(`[Task: ${taskLabel} | type: ${event.targetType ?? "task"}]`);
-        lines.push(`[Assigned by: ${event.senderName} (${event.senderId})]`);
+            ? `${event.targetName} (prll://${event.targetId})`
+            : `prll://${event.targetId}`;
+        lines.push(`[Task: ${taskLabel}]`);
+        lines.push(`[Assigned by: ${event.senderName} (prll://${event.senderId})]`);
         lines.push("", event.body);
     }
     return lines.join("\n");

package/dist/gateway-base.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"gateway-base.d.ts","sourceRoot":"","sources":["../src/gateway-base.ts"],"names":[],"mappings":"AAIA,OAAO,EAAuB,YAAY,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAC1E,OAAO,KAAK,EACV,qBAAqB,EAStB,MAAM,aAAa,CAAC;AAErB,OAAO,KAAK,EAEV,eAAe,EAGf,aAAa,EAEd,MAAM,uBAAuB,CAAC;AAmD/B,MAAM,MAAM,oBAAoB,GAAG;IACjC,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,YAAY,CAAC;IACrB,EAAE,EAAE,QAAQ,CAAC;IACb,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,MAAM,EAAE;QACN,UAAU,EAAE,MAAM,CAAC;QACnB,OAAO,EAAE,MAAM,CAAC;QAChB,MAAM,EAAE,MAAM,CAAC;KAChB,CAAC;IACF,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACrC,eAAe,EAAE,eAAe,CAAC;IACjC,GAAG,CAAC,EAAE,aAAa,CAAC;IACpB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,wBAAwB,CAAC,EAAE,CAAC,UAAU,EAAE,MAAM,KAAK,MAAM,GAAG,SAAS,CAAC;IACtE,cAAc,CAAC,EAAE,CAAC,IAAI,EAAE,qBAAqB,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IACvE,cAAc,CAAC,EAAE,CAAC,KAAK,EAAE;QAAE,eAAe,CAAC,EAAE,MAAM,CAAC;QAAC,EAAE,EAAE,QAAQ,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IACjH,kBAAkB,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;CACjD,CAAC;AAkCF,qBAAa,kBAAkB;IAuBjB,OAAO,CAAC,QAAQ,CAAC,IAAI;IAtBjC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAA+B;IAC3D,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAqC;IACtE,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAqB;IACrD,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAqB;IACxD,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAsC;IACjE,OAAO,CAAC,QAAQ,CAAC,aAAa,CAK5B;IAEF,OAAO,CAAC,SAAS,CAAM;IACvB,OAAO,CAAC,eAAe,CAAqB;IAC5C,OAAO,CAAC,cAAc,CAA+C;IACrE,OAAO,CAAC,kBAAkB,CAAS;IACnC,OAAO,CAAC,eAAe,CAAc;IACrC,OAAO,CAAC,QAAQ,CAAS;IAEzB,OAAO,CAAC,QAAQ,CAAC,uBAAuB,CAAQ;IAChD,OAAO,CAAC,QAAQ,CAAC,oBAAoB,CAAS;gBAEjB,IAAI,EAAE,oBAAoB;IAIjD,GAAG,CAAC,WAAW,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IA8ElD,OAAO,CAAC,eAAe;IAavB,OAAO,CAAC,WAAW;IAcnB,OAAO,CAAC,UAAU;IAWlB,OAAO,CAAC,oBAAoB;YAmBd,eAAe;YAqBf,iBAAiB;IAsF/B,OAAO,CAAC,eAAe;IASvB,OAAO,CAAC,eAAe;YAQT,gCAAgC;YAMhC,WAAW;YAyDX,gBAAgB;YAmEhB,eAAe;YAmDf,kBAAkB;YAoElB,kBAAkB;YAkBlB,4BAA4B;YA8D5B,aAAa;YA8Bb,oBAAoB;YAiCpB,mBAAmB;YAoGnB,WAAW;YA0DX,QAAQ;CAsBvB"}
+{"version":3,"file":"gateway-base.d.ts","sourceRoot":"","sources":["../src/gateway-base.ts"],"names":[],"mappings":"AAIA,OAAO,EAAuB,YAAY,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAC1E,OAAO,KAAK,EACV,qBAAqB,EAStB,MAAM,aAAa,CAAC;AAErB,OAAO,KAAK,EAEV,eAAe,EAGf,aAAa,EAEd,MAAM,uBAAuB,CAAC;AAmD/B,MAAM,MAAM,oBAAoB,GAAG;IACjC,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,YAAY,CAAC;IACrB,EAAE,EAAE,QAAQ,CAAC;IACb,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,MAAM,EAAE;QACN,UAAU,EAAE,MAAM,CAAC;QACnB,OAAO,EAAE,MAAM,CAAC;QAChB,MAAM,EAAE,MAAM,CAAC;KAChB,CAAC;IACF,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACrC,eAAe,EAAE,eAAe,CAAC;IACjC,GAAG,CAAC,EAAE,aAAa,CAAC;IACpB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,wBAAwB,CAAC,EAAE,CAAC,UAAU,EAAE,MAAM,KAAK,MAAM,GAAG,SAAS,CAAC;IACtE,cAAc,CAAC,EAAE,CAAC,IAAI,EAAE,qBAAqB,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IACvE,cAAc,CAAC,EAAE,CAAC,KAAK,EAAE;QAAE,eAAe,CAAC,EAAE,MAAM,CAAC;QAAC,EAAE,EAAE,QAAQ,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IACjH,kBAAkB,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;CACjD,CAAC;AAkCF,qBAAa,kBAAkB;IAuBjB,OAAO,CAAC,QAAQ,CAAC,IAAI;IAtBjC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAA+B;IAC3D,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAqC;IACtE,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAqB;IACrD,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAqB;IACxD,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAsC;IACjE,OAAO,CAAC,QAAQ,CAAC,aAAa,CAK5B;IAEF,OAAO,CAAC,SAAS,CAAM;IACvB,OAAO,CAAC,eAAe,CAAqB;IAC5C,OAAO,CAAC,cAAc,CAA+C;IACrE,OAAO,CAAC,kBAAkB,CAAS;IACnC,OAAO,CAAC,eAAe,CAAc;IACrC,OAAO,CAAC,QAAQ,CAAS;IAEzB,OAAO,CAAC,QAAQ,CAAC,uBAAuB,CAAQ;IAChD,OAAO,CAAC,QAAQ,CAAC,oBAAoB,CAAS;gBAEjB,IAAI,EAAE,oBAAoB;IAIjD,GAAG,CAAC,WAAW,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IA8ElD,OAAO,CAAC,eAAe;IAavB,OAAO,CAAC,WAAW;IAcnB,OAAO,CAAC,UAAU;IAWlB,OAAO,CAAC,oBAAoB;YAmBd,eAAe;YAqBf,iBAAiB;IAsF/B,OAAO,CAAC,eAAe;IASvB,OAAO,CAAC,eAAe;YAQT,gCAAgC;YAMhC,WAAW;YAyDX,gBAAgB;YAmEhB,eAAe;YAmDf,kBAAkB;YAoElB,kBAAkB;YAkBlB,4BAA4B;YA8D5B,aAAa;YA8Bb,oBAAoB;YAmCpB,mBAAmB;YAoGnB,WAAW;YA0DX,QAAQ;CAsBvB"}

package/dist/gateway-base.js

@@ -324,7 +324,7 @@ export class ParallAgentGateway {
         try {
             if (this.activeSessionId) {
                 try {
-                    await this.opts.client.updateAgentSession(this.opts.config.org_id, this.opts.agentUserId, this.activeSessionId, { status: "active" });
+                    await this.opts.client.updateAgentSession(this.opts.config.org_id, this.opts.agentUserId, this.activeSessionId, { status: "active", trigger_message_id: event.messageId });
                 }
                 catch (err) {
                     this.opts.log?.warn(`parall[${this.opts.accountId}]: failed to set session active: ${String(err)}`);
@@ -662,6 +662,10 @@ export class ParallAgentGateway {
         this.opts.log?.info(`parall[${this.opts.accountId}]: task assigned: ${task.identifier ?? task.id} "${task.title}"`);
         const parts = [`Title: ${task.title}`];
         parts.push(`Status: ${task.status}`, `Priority: ${task.priority}`);
+        if (task.project_id)
+            parts.push(`Project: prll://${task.project_id}`);
+        if (task.parent_id)
+            parts.push(`Parent: prll://${task.parent_id}`);
         if (task.description)
             parts.push("", task.description);
         const event = {

package/dist/index.d.ts

@@ -2,6 +2,7 @@ export * from "./types.js";
 export * from "./session-state.js";
 export * from "./routing.js";
 export * from "./event-format.js";
+export * from "./prompt-fragments.js";
 export * from "./dispatch-adapter.js";
 export * from "./gateway-base.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,cAAc,oBAAoB,CAAC;AACnC,cAAc,cAAc,CAAC;AAC7B,cAAc,mBAAmB,CAAC;AAClC,cAAc,uBAAuB,CAAC;AACtC,cAAc,mBAAmB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,cAAc,oBAAoB,CAAC;AACnC,cAAc,cAAc,CAAC;AAC7B,cAAc,mBAAmB,CAAC;AAClC,cAAc,uBAAuB,CAAC;AACtC,cAAc,uBAAuB,CAAC;AACtC,cAAc,mBAAmB,CAAC"}

package/dist/index.js

@@ -2,5 +2,6 @@ export * from "./types.js";
 export * from "./session-state.js";
 export * from "./routing.js";
 export * from "./event-format.js";
+export * from "./prompt-fragments.js";
 export * from "./dispatch-adapter.js";
 export * from "./gateway-base.js";

package/dist/prompt-fragments.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Shared prompt fragments for Parall agent runtimes.
+ * Each runtime adapter imports these and injects them via its own mechanism
+ * (OpenClaw: appendSystemContext, Claude Code: workspace file, etc.).
+ *
+ * This is the agent-facing SSOT for prll:// URI usage. The developer-facing
+ * architectural spec (BNF, canonicalization, data model) lives in
+ * docs/engineering-design/reference-schema-design.md. Different audiences,
+ * no duplication — this teaches agents HOW to use refs, the design doc
+ * explains WHY the system works the way it does.
+ */
+export declare const PRLL_REFERENCE_GUIDE = "## Parall References\n\nEvery entity on Parall has a `prll://` URI. Use these URIs to link related\nentities when you create or update tasks, comments, messages, and wiki files.\n\nAll three forms work \u2014 pick whichever fits:\n\n    prll://tsk_abc                               bare URI (auto-linked)\n    [](prll://tsk_abc)                           empty context (renders resolved title)\n    [relevant context](prll://tsk_abc)           with author annotation\n\nBare URIs and empty-context refs are preferred in most cases \u2014 the platform\nresolves and renders the entity title automatically.\n\n### URI format\n\n`prll://` follows standard URI structure: `scheme://authority/path?query#fragment`.\n\n**Entities** \u2014 the entity ID is the authority:\n\n    prll://usr_xxx          user          prll://prj_xxx          project\n    prll://tsk_xxx          task          prll://wik_xxx          wiki\n    prll://msg_xxx          message       prll://tcm_xxx          task comment\n    prll://cht_xxx          chat          prll://ase_xxx          agent session\n\n**Wiki** \u2014 path is file path, fragment is a typed anchor:\n\n    prll://wik_xxx/docs/guide.md                  file\n    prll://wik_xxx/docs/guide.md#h=Auth::OAuth    heading (:: = hierarchy)\n    prll://wik_xxx/src/auth.go?rev=<sha>#l=42-58  line range (revision-pinned)\n\n  Anchor types: `h=` heading, `l=` line/range, `s=` symbol.\n  Line anchors in persistent content require `?rev=<full-40-char-sha>`.\n\n**Chat message range**:\n\n    prll://cht_xxx#range=msg_01HA,msg_01HZ\n\n**Field access** \u2014 path selects a field (omit to reference the entity itself):\n\n    prll://tsk_xxx/description#Implementation     heading within task description\n\n### When to reference\n\n- **Origin** \u2014 always link the message or task that triggered your work\n- **Design docs / wiki** \u2014 link specs and guides relevant to the work\n- **Related tasks** \u2014 link parent, sibling, or blocking tasks\n- **People** \u2014 link assignees or stakeholders when mentioning them\n- **Conversations** \u2014 link a chat or message range as context\n\n### Why this matters\n\nOther agents and humans read your output. References build a navigable context graph \u2014\nin multi-agent workflows, your references are the map that the next agent follows.";
+//# sourceMappingURL=prompt-fragments.d.ts.map

package/dist/prompt-fragments.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompt-fragments.d.ts","sourceRoot":"","sources":["../src/prompt-fragments.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,eAAO,MAAM,oBAAoB,6xEAqDkD,CAAC"}

package/dist/prompt-fragments.js

@@ -0,0 +1,65 @@
+/**
+ * Shared prompt fragments for Parall agent runtimes.
+ * Each runtime adapter imports these and injects them via its own mechanism
+ * (OpenClaw: appendSystemContext, Claude Code: workspace file, etc.).
+ *
+ * This is the agent-facing SSOT for prll:// URI usage. The developer-facing
+ * architectural spec (BNF, canonicalization, data model) lives in
+ * docs/engineering-design/reference-schema-design.md. Different audiences,
+ * no duplication — this teaches agents HOW to use refs, the design doc
+ * explains WHY the system works the way it does.
+ */
+export const PRLL_REFERENCE_GUIDE = `## Parall References
+
+Every entity on Parall has a \`prll://\` URI. Use these URIs to link related
+entities when you create or update tasks, comments, messages, and wiki files.
+
+All three forms work — pick whichever fits:
+
+    prll://tsk_abc                               bare URI (auto-linked)
+    [](prll://tsk_abc)                           empty context (renders resolved title)
+    [relevant context](prll://tsk_abc)           with author annotation
+
+Bare URIs and empty-context refs are preferred in most cases — the platform
+resolves and renders the entity title automatically.
+
+### URI format
+
+\`prll://\` follows standard URI structure: \`scheme://authority/path?query#fragment\`.
+
+**Entities** — the entity ID is the authority:
+
+    prll://usr_xxx          user          prll://prj_xxx          project
+    prll://tsk_xxx          task          prll://wik_xxx          wiki
+    prll://msg_xxx          message       prll://tcm_xxx          task comment
+    prll://cht_xxx          chat          prll://ase_xxx          agent session
+
+**Wiki** — path is file path, fragment is a typed anchor:
+
+    prll://wik_xxx/docs/guide.md                  file
+    prll://wik_xxx/docs/guide.md#h=Auth::OAuth    heading (:: = hierarchy)
+    prll://wik_xxx/src/auth.go?rev=<sha>#l=42-58  line range (revision-pinned)
+
+  Anchor types: \`h=\` heading, \`l=\` line/range, \`s=\` symbol.
+  Line anchors in persistent content require \`?rev=<full-40-char-sha>\`.
+
+**Chat message range**:
+
+    prll://cht_xxx#range=msg_01HA,msg_01HZ
+
+**Field access** — path selects a field (omit to reference the entity itself):
+
+    prll://tsk_xxx/description#Implementation     heading within task description
+
+### When to reference
+
+- **Origin** — always link the message or task that triggered your work
+- **Design docs / wiki** — link specs and guides relevant to the work
+- **Related tasks** — link parent, sibling, or blocking tasks
+- **People** — link assignees or stakeholders when mentioning them
+- **Conversations** — link a chat or message range as context
+
+### Why this matters
+
+Other agents and humans read your output. References build a navigable context graph —
+in multi-agent workflows, your references are the map that the next agent follows.`;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@parall/agent-core",
-  "version": "1.14.5",
+  "version": "1.15.1",
   "description": "Shared agent runtime orchestration helpers for Parall",
   "license": "MIT",
   "repository": {
@@ -22,7 +22,7 @@
     "src"
   ],
   "dependencies": {
-    "@parall/sdk": "1.14.5"
+    "@parall/sdk": "1.15.1"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",

package/src/event-format.ts

@@ -5,12 +5,12 @@ export function buildEventBody(event: ParallEvent): string {
   if (event.type === "message") {
     lines.push(`[Event: message.new]`);
     const chatLabel = event.targetName
-      ? `"${event.targetName}" (${event.targetId})`
-      : event.targetId;
+      ? `"${event.targetName}" (prll://${event.targetId})`
+      : `prll://${event.targetId}`;
     lines.push(`[Chat: ${chatLabel} | type: ${event.targetType ?? "unknown"}]`);
-    lines.push(`[From: ${event.senderName} (${event.senderId})]`);
-    lines.push(`[Message ID: ${event.messageId}]`);
-    if (event.threadRootId) lines.push(`[Thread: ${event.threadRootId}]`);
+    lines.push(`[From: ${event.senderName} (prll://${event.senderId})]`);
+    lines.push(`[Message ID: prll://${event.messageId}]`);
+    if (event.threadRootId) lines.push(`[Thread: prll://${event.threadRootId}]`);
     if (event.noReply) lines.push(`[Hint: no_reply]`);
     if (event.mediaFields?.MediaUrl) {
       lines.push(`[Attachment: ${event.mediaFields.MediaType ?? "file"} ${event.mediaFields.MediaUrl}]`);
@@ -19,10 +19,10 @@ export function buildEventBody(event: ParallEvent): string {
   } else {
     lines.push(`[Event: task.assigned]`);
     const taskLabel = event.targetName
-      ? `${event.targetName} (${event.targetId})`
-      : event.targetId;
-    lines.push(`[Task: ${taskLabel} | type: ${event.targetType ?? "task"}]`);
-    lines.push(`[Assigned by: ${event.senderName} (${event.senderId})]`);
+      ? `${event.targetName} (prll://${event.targetId})`
+      : `prll://${event.targetId}`;
+    lines.push(`[Task: ${taskLabel}]`);
+    lines.push(`[Assigned by: ${event.senderName} (prll://${event.senderId})]`);
     lines.push("", event.body);
   }
   return lines.join("\n");

package/src/gateway-base.ts

@@ -437,7 +437,7 @@ export class ParallAgentGateway {
     try {
       if (this.activeSessionId) {
         try {
-          await this.opts.client.updateAgentSession(this.opts.config.org_id, this.opts.agentUserId, this.activeSessionId, { status: "active" });
+          await this.opts.client.updateAgentSession(this.opts.config.org_id, this.opts.agentUserId, this.activeSessionId, { status: "active", trigger_message_id: event.messageId });
         } catch (err) {
           this.opts.log?.warn(`parall[${this.opts.accountId}]: failed to set session active: ${String(err)}`);
         }
@@ -784,6 +784,8 @@ export class ParallAgentGateway {
 
     const parts = [`Title: ${task.title}`];
     parts.push(`Status: ${task.status}`, `Priority: ${task.priority}`);
+    if (task.project_id) parts.push(`Project: prll://${task.project_id}`);
+    if (task.parent_id) parts.push(`Parent: prll://${task.parent_id}`);
     if (task.description) parts.push("", task.description);
 
     const event: ParallEvent = {

package/src/index.ts

@@ -2,5 +2,6 @@ export * from "./types.js";
 export * from "./session-state.js";
 export * from "./routing.js";
 export * from "./event-format.js";
+export * from "./prompt-fragments.js";
 export * from "./dispatch-adapter.js";
 export * from "./gateway-base.js";

package/src/prompt-fragments.ts

@@ -0,0 +1,66 @@
+/**
+ * Shared prompt fragments for Parall agent runtimes.
+ * Each runtime adapter imports these and injects them via its own mechanism
+ * (OpenClaw: appendSystemContext, Claude Code: workspace file, etc.).
+ *
+ * This is the agent-facing SSOT for prll:// URI usage. The developer-facing
+ * architectural spec (BNF, canonicalization, data model) lives in
+ * docs/engineering-design/reference-schema-design.md. Different audiences,
+ * no duplication — this teaches agents HOW to use refs, the design doc
+ * explains WHY the system works the way it does.
+ */
+
+export const PRLL_REFERENCE_GUIDE = `## Parall References
+
+Every entity on Parall has a \`prll://\` URI. Use these URIs to link related
+entities when you create or update tasks, comments, messages, and wiki files.
+
+All three forms work — pick whichever fits:
+
+    prll://tsk_abc                               bare URI (auto-linked)
+    [](prll://tsk_abc)                           empty context (renders resolved title)
+    [relevant context](prll://tsk_abc)           with author annotation
+
+Bare URIs and empty-context refs are preferred in most cases — the platform
+resolves and renders the entity title automatically.
+
+### URI format
+
+\`prll://\` follows standard URI structure: \`scheme://authority/path?query#fragment\`.
+
+**Entities** — the entity ID is the authority:
+
+    prll://usr_xxx          user          prll://prj_xxx          project
+    prll://tsk_xxx          task          prll://wik_xxx          wiki
+    prll://msg_xxx          message       prll://tcm_xxx          task comment
+    prll://cht_xxx          chat          prll://ase_xxx          agent session
+
+**Wiki** — path is file path, fragment is a typed anchor:
+
+    prll://wik_xxx/docs/guide.md                  file
+    prll://wik_xxx/docs/guide.md#h=Auth::OAuth    heading (:: = hierarchy)
+    prll://wik_xxx/src/auth.go?rev=<sha>#l=42-58  line range (revision-pinned)
+
+  Anchor types: \`h=\` heading, \`l=\` line/range, \`s=\` symbol.
+  Line anchors in persistent content require \`?rev=<full-40-char-sha>\`.
+
+**Chat message range**:
+
+    prll://cht_xxx#range=msg_01HA,msg_01HZ
+
+**Field access** — path selects a field (omit to reference the entity itself):
+
+    prll://tsk_xxx/description#Implementation     heading within task description
+
+### When to reference
+
+- **Origin** — always link the message or task that triggered your work
+- **Design docs / wiki** — link specs and guides relevant to the work
+- **Related tasks** — link parent, sibling, or blocking tasks
+- **People** — link assignees or stakeholders when mentioning them
+- **Conversations** — link a chat or message range as context
+
+### Why this matters
+
+Other agents and humans read your output. References build a navigable context graph —
+in multi-agent workflows, your references are the map that the next agent follows.`;