egregore-artifacts 0.5.0 → 0.9.5

package/bin/cli.js

@@ -4,7 +4,7 @@ import { execSync } from 'node:child_process';
 import fs from 'node:fs';
 import path from 'node:path';
 
-const KNOWN_TYPES = ['quest', 'handoff', 'activity', 'document', 'board', 'network'];
+const KNOWN_TYPES = ['quest', 'handoff', 'handoff-v1', 'activity', 'document', 'board', 'network'];
 const args = process.argv.slice(2);
 
 let type, filePath;
@@ -26,17 +26,27 @@ if (args.length === 0) {
 // Parse flags
 let outputFile = null;
 let noOpen = false;
+let orgSlug = null;
+let viewBase = null;
 const positional = [];
 for (let i = 0; i < args.length; i++) {
   if (args[i] === '--output' || args[i] === '-o') {
     outputFile = args[++i];
   } else if (args[i] === '--no-open') {
     noOpen = true;
+  } else if (args[i] === '--org-slug') {
+    orgSlug = args[++i];
+  } else if (args[i] === '--view-base') {
+    viewBase = args[++i];
   } else {
     positional.push(args[i]);
   }
 }
 
+// Default view base; slug is intentionally left null unless supplied so OSS
+// mode (which cannot predict URLs) falls through to plain <code> rendering.
+if (!viewBase) viewBase = 'https://egregore.xyz/view';
+
 // If first positional is a known type, use it. Otherwise treat it as a file path.
 if (KNOWN_TYPES.includes(positional[0])) {
   type = positional[0];
@@ -83,7 +93,7 @@ function resolveFile(fp) {
 
 try {
   const input = (type === 'activity' || type === 'board' || type === 'network') ? (filePath || 'live') : resolveFile(filePath);
-  const html = await generateArtifact(type, input);
+  const html = await generateArtifact(type, input, { orgSlug, viewBase });
   const slug = filePath ? filePath.split('/').pop().replace('.md', '') : new Date().toISOString().split('T')[0];
 
   if (outputFile) {

package/lib/artifact-id.js

@@ -0,0 +1,28 @@
+// Deterministic artifact IDs for memory files.
+//
+// Emits `{prefix}-{12 hex}` where prefix is derived from the file extension
+// (m = .md, h = .html) and the hex is the first 12 chars of sha256(canonical_path).
+//
+// Kept in parity with bin/lib/artifact-id.sh — both MUST produce identical
+// output for the same input. Parity is enforced by test/artifact-id.test.js.
+import { createHash } from 'node:crypto';
+
+const EXT_PREFIX = { '.md': 'm', '.html': 'h' };
+
+function canonicalize(path) {
+  return path.replace(/^\.\//, '').replace(/\/{2,}/g, '/');
+}
+
+function extension(path) {
+  const m = path.match(/\.[a-z0-9]+$/i);
+  return m ? m[0].toLowerCase() : '';
+}
+
+export function artifactIdFromPath(rawPath) {
+  if (!rawPath || typeof rawPath !== 'string') return null;
+  const canonical = canonicalize(rawPath);
+  const prefix = EXT_PREFIX[extension(canonical)];
+  if (!prefix) return null;
+  const hash = createHash('sha256').update(canonical).digest('hex').slice(0, 12);
+  return `${prefix}-${hash}`;
+}

package/lib/comments.js

@@ -0,0 +1,248 @@
+// Comment thread + composer — renders inline at the bottom of any
+// `/view`-rendered artifact. Reads markdown files from
+// `memory/comments/{kind}/{id}/*.md`. No graph access — filesystem only,
+// so it works in both connected and local mode.
+import React from 'react';
+import fs from 'node:fs';
+import path from 'node:path';
+import { execSync } from 'node:child_process';
+import { renderMarkdown } from './markdown.js';
+
+const h = React.createElement;
+
+// ── Path resolution ─────────────────────────────────────────────
+
+function findGitRoot(startPath) {
+  try {
+    return execSync('git rev-parse --show-toplevel 2>/dev/null', {
+      encoding: 'utf-8',
+      cwd: startPath || process.cwd(),
+    }).trim();
+  } catch {
+    return null;
+  }
+}
+
+// Derive (parentKind, parentId) for a rendered artifact.
+// Mirrors the indexer's parent_kind enum: quest|handoff|card|decision|document.
+export function derivedParent(type, filePath) {
+  if (!filePath || typeof filePath !== 'string') return null;
+
+  const base = path.basename(filePath, '.md');
+
+  if (type === 'quest') {
+    return { kind: 'quest', id: base };
+  }
+  if (type === 'handoff') {
+    // sessionId can be either YYYY-MM-DD-author-topic (flat) or DD-author-topic
+    // inside a YYYY-MM/ subdir. Mirror bin/index-handoff.sh's id derivation.
+    const dir = path.basename(path.dirname(filePath));
+    if (/^\d{4}-\d{2}$/.test(dir)) {
+      return { kind: 'handoff', id: `${dir}-${base}` };
+    }
+    return { kind: 'handoff', id: base };
+  }
+  if (type === 'document') {
+    if (filePath.includes('/knowledge/decisions/')) {
+      return { kind: 'decision', id: base };
+    }
+    return { kind: 'document', id: base };
+  }
+  return null;
+}
+
+// ── Loader ──────────────────────────────────────────────────────
+
+export function loadComments(parent, gitRootHint) {
+  if (!parent || !parent.kind || !parent.id) return [];
+
+  const gitRoot = gitRootHint || findGitRoot();
+  if (!gitRoot) return [];
+
+  const dir = path.join(gitRoot, 'memory', 'comments', parent.kind, parent.id);
+  if (!fs.existsSync(dir)) return [];
+
+  const files = fs.readdirSync(dir)
+    .filter(f => f.endsWith('.md'))
+    .sort();
+
+  return files.map(f => parseCommentFile(path.join(dir, f))).filter(Boolean);
+}
+
+function parseCommentFile(filePath) {
+  const raw = fs.readFileSync(filePath, 'utf-8');
+  const id = path.basename(filePath, '.md');
+
+  const fmMatch = raw.match(/^---\n([\s\S]*?)\n---\n([\s\S]*)$/);
+  if (!fmMatch) return null;
+
+  const fm = parseSimpleYaml(fmMatch[1]);
+  const body = fmMatch[2].trim();
+
+  return {
+    id,
+    parentKind: fm.parent_kind,
+    parentId: fm.parent_id,
+    author: fm.author,
+    to: fm.to || [],
+    replyTo: fm.reply_to || null,
+    createdAt: fm.created || null,
+    body,
+  };
+}
+
+function parseSimpleYaml(text) {
+  const result = {};
+  for (const line of text.split('\n')) {
+    const m = line.match(/^([\w_-]+):\s*(.*)$/);
+    if (!m) continue;
+    const [, key, rawVal] = m;
+    let val = rawVal.trim();
+    if (val.startsWith('[') && val.endsWith(']')) {
+      val = val.slice(1, -1).split(',').map(s => s.trim().replace(/^["']|["']$/g, '')).filter(Boolean);
+    } else if ((val.startsWith('"') && val.endsWith('"')) || (val.startsWith("'") && val.endsWith("'"))) {
+      val = val.slice(1, -1);
+    } else if (val === 'null' || val === '') {
+      val = null;
+    }
+    result[key] = val;
+  }
+  return result;
+}
+
+// ── Threading ───────────────────────────────────────────────────
+
+// Build a tree from a flat list using replyTo. Top-level items keep their order;
+// each child renders inline under its parent. Orphaned replies (parent missing)
+// are promoted to top-level so nothing disappears.
+function buildThreads(comments) {
+  const byId = new Map(comments.map(c => [c.id, { ...c, children: [] }]));
+  const roots = [];
+  for (const c of byId.values()) {
+    if (c.replyTo && byId.has(c.replyTo)) {
+      byId.get(c.replyTo).children.push(c);
+    } else {
+      roots.push(c);
+    }
+  }
+  return roots;
+}
+
+function formatDate(iso) {
+  if (!iso) return '';
+  try {
+    return new Date(iso).toLocaleDateString('en-US', {
+      month: 'short', day: 'numeric', hour: '2-digit', minute: '2-digit',
+    });
+  } catch {
+    return iso;
+  }
+}
+
+// ── Components ──────────────────────────────────────────────────
+
+function Comment({ comment, depth }) {
+  const indent = depth > 0 ? { marginLeft: `${Math.min(depth, 3) * 1.5}rem` } : {};
+  const recipients = (comment.to || []).filter(Boolean);
+
+  return h('div', { className: 'eg-comment', style: indent, 'data-comment-id': comment.id },
+    h('div', { className: 'eg-comment-meta' },
+      h('span', { className: 'eg-comment-avatar' },
+        (comment.author || '?')[0].toUpperCase()
+      ),
+      h('span', { className: 'eg-comment-author' }, comment.author || 'unknown'),
+      comment.createdAt && h('span', { className: 'eg-comment-date' }, formatDate(comment.createdAt)),
+      recipients.length > 0 && h('span', { className: 'eg-comment-to' },
+        '→ ', recipients.join(', ')
+      ),
+    ),
+    h('div', { className: 'eg-comment-body' }, renderMarkdown(comment.body)),
+    h('div', { className: 'eg-comment-actions' },
+      h('button', {
+        type: 'button',
+        className: 'eg-comment-reply',
+        'data-reply-to': comment.id,
+        'data-reply-author': comment.author || '',
+      }, '↩ reply'),
+    ),
+    ...(comment.children || []).map(child =>
+      h(Comment, { key: child.id, comment: child, depth: depth + 1 })
+    ),
+  );
+}
+
+function CommentThread({ comments }) {
+  if (!comments || comments.length === 0) {
+    return h('div', { className: 'eg-comments-empty' },
+      'No comments yet. Be the first.'
+    );
+  }
+  const roots = buildThreads(comments);
+  return h('div', { className: 'eg-comments-thread' },
+    ...roots.map(c => h(Comment, { key: c.id, comment: c, depth: 0 }))
+  );
+}
+
+function CommentComposer({ parent }) {
+  return h('div', {
+    className: 'eg-comments-composer',
+    'data-parent-kind': parent.kind,
+    'data-parent-id': parent.id,
+  },
+    h('div', { className: 'eg-card-title' },
+      h('span', { className: 'eg-live-only' }, 'Add a comment to '),
+      h('span', { className: 'eg-paste-only' }, 'Compose a comment on '),
+      h('code', { className: 'eg-comment-target' }, `${parent.kind}/${parent.id}`),
+    ),
+    h('textarea', {
+      className: 'eg-comment-textarea',
+      placeholder: 'Type your comment. @handle to ping someone. Markdown is supported.',
+      rows: 4,
+    }),
+
+    h('div', { className: 'eg-comment-preview-label' },
+      h('span', { className: 'eg-live-only' }, 'Preview:'),
+      h('span', { className: 'eg-paste-only' }, 'Paste this in your Claude terminal:'),
+    ),
+    h('div', { className: 'eg-comment-preview-frame' },
+      h('pre', { className: 'eg-comment-preview' },
+        h('code', { className: 'eg-comment-preview-code' }, ''),
+      ),
+      h('button', {
+        type: 'button',
+        className: 'eg-comment-copy-btn',
+        'aria-label': 'Copy snippet',
+      }, 'Copy'),
+    ),
+    h('div', { className: 'eg-comment-status', 'aria-live': 'polite' }),
+
+    // Primary action — only visible when the loopback server is reachable.
+    h('button', {
+      type: 'button',
+      className: 'eg-comment-post-btn eg-live-only',
+    }, 'Post comment'),
+
+    h('div', { className: 'eg-comment-help' },
+      h('span', { className: 'eg-live-only' },
+        'Posts directly via the local /view server. Writes the file, indexes the graph, fires Telegram for any @mentions, and commits to memory.',
+      ),
+      h('span', { className: 'eg-paste-only' },
+        'The browser can’t write to your filesystem or run git, so the snippet is the handoff. Claude recognizes the marker and runs the publish flow.',
+      ),
+    ),
+  );
+}
+
+export function CommentSection({ parent, comments }) {
+  if (!parent) return null;
+  return h('section', { className: 'eg-comments-section' },
+    h('div', { className: 'eg-comments-heading' },
+      h('span', null, 'Comments'),
+      comments && comments.length > 0 && h('span', { className: 'eg-comments-count' },
+        ` (${comments.length})`
+      ),
+    ),
+    h(CommentThread, { comments }),
+    h(CommentComposer, { parent }),
+  );
+}

package/lib/components.js

@@ -1,7 +1,7 @@
 // Branded Egregore React components — no JSX, uses React.createElement
 import React from 'react';
 import { colors, fonts, typography } from './tokens.js';
-import { renderMarkdown } from './markdown.js';
+import { renderMarkdown, inlineMarkdown } from './markdown.js';
 
 const h = React.createElement;
 
@@ -105,7 +105,7 @@ export function BulletList({ items }) {
 
   return h('ul', { className: 'eg-bullet-list' },
     ...items.map((item, i) =>
-      h('li', { key: i }, item)
+      h('li', { key: i }, inlineMarkdown(item))
     ),
   );
 }

package/lib/index.js

@@ -5,22 +5,31 @@ import os from 'node:os';
 import { renderToHtml, renderSpecToHtml } from './render.js';
 import { parseQuest } from './parsers/quest.js';
 import { parseHandoff } from './parsers/handoff.js';
+import { parseHandoffV1 } from './parsers/handoff-v1.js';
 import { parseActivity } from './parsers/activity.js';
 import { parseDocument } from './parsers/document.js';
 import { parseBoard } from './parsers/board.js';
 import { parseNetwork } from './parsers/network.js';
 import { questTemplate } from './templates/quest.js';
 import { handoffTemplate } from './templates/handoff.js';
+import { handoffV1Template } from './templates/handoff-v1.js';
 import { activityTemplate } from './templates/activity.js';
 import { documentTemplate } from './templates/document.js';
 import { boardTemplate } from './templates/board.js';
 import { networkTemplate } from './templates/network.js';
 import { openInBrowser } from './open.js';
+import { setLinkContext, clearLinkContext } from './markdown.js';
+import { derivedParent, loadComments } from './comments.js';
 
-const PARSERS = { quest: parseQuest, handoff: parseHandoff, activity: parseActivity, document: parseDocument, board: parseBoard, network: parseNetwork };
-const TEMPLATES = { quest: questTemplate, handoff: handoffTemplate, activity: activityTemplate, document: documentTemplate, board: boardTemplate, network: networkTemplate };
+const PARSERS = { quest: parseQuest, handoff: parseHandoff, 'handoff-v1': parseHandoffV1, activity: parseActivity, document: parseDocument, board: parseBoard, network: parseNetwork };
+const TEMPLATES = { quest: questTemplate, handoff: handoffTemplate, 'handoff-v1': handoffV1Template, activity: activityTemplate, document: documentTemplate, board: boardTemplate, network: networkTemplate };
 
-export async function generateArtifact(type, input) {
+// Types that participate in the comments system. Skipped: board (interactive
+// editor with its own UI), activity/network (live feeds without a stable
+// parent_id).
+const COMMENTABLE_TYPES = new Set(['quest', 'handoff', 'document']);
+
+export async function generateArtifact(type, input, options = {}) {
   const template = TEMPLATES[type];
   if (!template) throw new Error(`Unknown artifact type: ${type}. Available: ${Object.keys(TEMPLATES).join(', ')}`);
 
@@ -33,8 +42,28 @@ export async function generateArtifact(type, input) {
     data = input;
   }
 
-  const element = template(data);
-  return renderToHtml(element, { title: data.title || 'Untitled', type });
+  // Comments — only when rendering from a real file path and the type supports them.
+  let parent = null;
+  let comments = [];
+  if (typeof input === 'string' && COMMENTABLE_TYPES.has(type)) {
+    parent = derivedParent(type, input);
+    if (parent) comments = loadComments(parent);
+  }
+
+  // Link context for inlineMarkdown — only enabled when both values are supplied.
+  // Missing either falls through to plain <code> rendering (OSS mode).
+  setLinkContext({ viewBase: options.viewBase, orgSlug: options.orgSlug });
+  try {
+    const element = template(data);
+    return renderToHtml(element, {
+      title: data.title || 'Untitled',
+      type,
+      parent,
+      comments,
+    });
+  } finally {
+    clearLinkContext();
+  }
 }
 
 export async function openArtifact(html, title = 'Egregore Artifact') {

package/lib/markdown.js

@@ -2,9 +2,34 @@
 // Handles: **bold**, *italic*, `code`, ### headings, [links](url), tables, lists
 import React from 'react';
 import { colors, fonts } from './tokens.js';
+import { artifactIdFromPath } from './artifact-id.js';
 
 const h = React.createElement;
 
+// Module-level link context. Set by generateArtifact() before rendering, read
+// by inlineMarkdown() when deciding whether to rewrite `memory/…` code spans
+// and bare egregore.xyz URLs into <a> tags. Renders are synchronous so this
+// is safe; missing context falls through to plain-<code> behaviour (OSS mode).
+let linkContext = { viewBase: null, orgSlug: null };
+
+export function setLinkContext(ctx) {
+  linkContext = {
+    viewBase: (ctx && ctx.viewBase) || null,
+    orgSlug: (ctx && ctx.orgSlug) || null,
+  };
+}
+
+export function clearLinkContext() {
+  linkContext = { viewBase: null, orgSlug: null };
+}
+
+function memoryPathHref(memoryPath) {
+  if (!linkContext.viewBase || !linkContext.orgSlug) return null;
+  const id = artifactIdFromPath(memoryPath);
+  if (!id) return null;
+  return `${linkContext.viewBase}/${linkContext.orgSlug}/${id}`;
+}
+
 export function renderMarkdown(text) {
   if (!text) return null;
 
@@ -237,7 +262,7 @@ export function renderMarkdown(text) {
 
 // Inline markdown: **bold**, *italic*, `code`, [link](url)
 // Finds whichever pattern appears earliest in the string
-function inlineMarkdown(text) {
+export function inlineMarkdown(text) {
   if (!text) return text;
 
   const parts = [];
@@ -245,6 +270,27 @@ function inlineMarkdown(text) {
   let key = 0;
 
   const patterns = [
+    // Backtick-wrapped memory/*.{md,html} → link to its own published view
+    // when linkContext is available (connected mode). Falls through to plain
+    // <code> otherwise via the generic `code` pattern below.
+    { re: /`(memory\/[^`\s]+\.(?:md|html))`/, render: (m) => {
+      const href = memoryPathHref(m[1]);
+      if (!href) return h('code', { key: key++, className: 'eg-code' }, m[1]);
+      return h('a', {
+        key: key++,
+        href,
+        style: { color: 'var(--terracotta)', textDecoration: 'none' },
+      }, h('code', { className: 'eg-code' }, m[1]));
+    } },
+    // Bare http(s) URLs → auto-linked <a>. URLs inside `code`, **bold**, or
+    // [text](url) spans are unaffected because those patterns match at an
+    // earlier index and win the "earliest wins" race. Regex excludes common
+    // trailing punctuation so "See https://foo.com." doesn't eat the period,
+    // and excludes quote characters so "href=\"https://x.com\"" or inline
+    // strings like 'see https://x.com' terminate cleanly at the quote.
+    { re: /https?:\/\/[^\s)`<>"']*[^\s)`<>"'.,;:!?]/, render: (m) => h('a', {
+      key: key++, href: m[0], style: { color: 'var(--terracotta)', textDecoration: 'underline' },
+    }, m[0]) },
     { re: /`([^`]+)`/, render: (m) => h('code', {
       key: key++,
       className: 'eg-code',
@@ -359,8 +405,10 @@ function parseTableRow(line) {
   return line.replace(/^\|/, '').replace(/\|$/, '').split('|');
 }
 
-// Lightweight markdown renderer — tables + paragraphs only, no inline regex
-// Use for large attachments where full inlineMarkdown is too expensive
+// Lightweight markdown renderer — tables, bullets, and paragraphs. Pipes
+// items and paragraph text through inlineMarkdown so attachments pick up
+// auto-linking of memory paths and bare URLs. Skips the full block grammar
+// (headings beyond H2, ordered lists, code fences) for speed on large inputs.
 export function renderMarkdownLite(text) {
   if (!text) return null;
 
@@ -397,7 +445,7 @@ export function renderMarkdownLite(text) {
         i++;
       }
       elements.push(h('ul', { key: elements.length, style: { listStyle: 'disc', paddingLeft: '1.5rem', margin: '0.5rem 0' } },
-        ...items.map((item, j) => h('li', { key: j, style: { fontSize: '14px', lineHeight: 1.5, marginBottom: '0.25rem' } }, item)),
+        ...items.map((item, j) => h('li', { key: j, style: { fontSize: '14px', lineHeight: 1.5, marginBottom: '0.25rem' } }, inlineMarkdown(item))),
       ));
       continue;
     }
@@ -406,7 +454,7 @@ export function renderMarkdownLite(text) {
     if (line.trim() === '') { i++; continue; }
 
     // Paragraph
-    elements.push(h('p', { key: elements.length, style: { margin: '0.5rem 0', fontSize: '14px', lineHeight: 1.6, color: 'var(--dark)' } }, line));
+    elements.push(h('p', { key: elements.length, style: { margin: '0.5rem 0', fontSize: '14px', lineHeight: 1.6, color: 'var(--dark)' } }, inlineMarkdown(line)));
     i++;
   }
 

package/lib/parsers/handoff-v1.js

@@ -0,0 +1,65 @@
+// Parse v1 handoff JSON (canonical format per docs/specs/handoff-format-v1.md).
+// Input: file path to a JSON file, OR a JSON string, OR a parsed object.
+// Output: the canonical v1 object normalized for the template.
+import fs from 'node:fs';
+
+export function parseHandoffV1(input) {
+  let obj;
+
+  if (typeof input === 'string') {
+    if (input.trim().startsWith('{')) {
+      obj = JSON.parse(input);
+    } else {
+      if (!fs.existsSync(input)) throw new Error(`File not found: ${input}`);
+      const raw = fs.readFileSync(input, 'utf-8');
+      obj = JSON.parse(raw);
+    }
+  } else if (typeof input === 'object' && input !== null) {
+    obj = input;
+  } else {
+    throw new Error('parseHandoffV1 expects a file path, JSON string, or object');
+  }
+
+  // Light validation — surface clear errors.
+  if (obj['@context'] !== 'https://egregore.xyz/spec/handoff/v1') {
+    throw new Error(`Unexpected @context: ${obj['@context']} (expected handoff/v1)`);
+  }
+  if (!obj.topic || !obj.claim || !obj.author || !obj.body) {
+    throw new Error('Missing required v1 fields (topic, claim, author, body)');
+  }
+
+  // Normalize: ensure arrays exist; preserve everything else as-is.
+  return {
+    '@context': obj['@context'],
+    id:                    obj.id || null,
+    version:               obj.version || '1.0',
+    kind:                  obj.kind || 'handoff',
+    topic:                 obj.topic,
+    claim:                 obj.claim,
+    ask:                   obj.ask || null,
+    created_at:            obj.created_at || null,
+    updated_at:            obj.updated_at || null,
+    author:                obj.author,
+    audience:              obj.audience || { addressed_to: [], visible_to: 'public', extendable_by: 'anyone' },
+    parents:               Array.isArray(obj.parents)    ? obj.parents    : [],
+    body:                  obj.body,
+    references:            Array.isArray(obj.references) ? obj.references : [],
+    repo_state:            Array.isArray(obj.repo_state) ? obj.repo_state : null,
+    depth:                 obj.depth || 'shallow',
+    deep_context:          obj.deep_context || null,
+    receiver_instructions: obj.receiver_instructions || null,
+    extensions:            Array.isArray(obj.extensions) ? obj.extensions : [],
+    // Convenience for the template:
+    title:                 obj.topic,
+    canonical_url:         obj.id || null,
+    extension_endpoint:    obj.id ? deriveExtensionEndpoint(obj.id) : null,
+  };
+}
+
+function deriveExtensionEndpoint(canonicalUrl) {
+  // Canonical URL pattern: https://egregore.xyz/view/_/{id}
+  // Extension endpoint: https://egregore.xyz/api/artifacts/handoff/{id}/extend
+  const m = canonicalUrl.match(/\/(?:view\/_|h)\/([a-zA-Z0-9_-]+)/);
+  if (!m) return null;
+  return `https://egregore.xyz/api/artifacts/handoff/${m[1]}/extend`;
+}

package/lib/parsers/handoff.js

@@ -131,7 +131,14 @@ function deriveSessionIdFromPath(filePath) {
 }
 
 function tryLiveSubgraphQuery(sessionId, gitRoot) {
+  // 1-hop neighbors + 2-hop artifact→quest linkage. The artifactQuestLinks
+  // collection lets the renderer draw the :PART_OF edges from artifacts up
+  // to the quests they belong to — the feature that makes this a graph
+  // instead of a list.
   const cypher = `MATCH (s:Session {id: $sessionId})
+OPTIONAL MATCH (s)-[:BY]->(author:Person)
+OPTIONAL MATCH (s)-[:HANDED_TO]->(recipient:Person)
+OPTIONAL MATCH (s)-[:ABOUT]->(project:Project)
 OPTIONAL MATCH (s)-[:IMPLEMENTS]->(prior:Session)
 OPTIONAL MATCH (prior)-[:BY]->(priorAuthor:Person)
 OPTIONAL MATCH (later:Session)-[:IMPLEMENTS]->(s)
@@ -140,13 +147,18 @@ OPTIONAL MATCH (s)-[:CONTINUES]->(cont:Session)
 OPTIONAL MATCH (cont)-[:BY]->(contAuthor:Person)
 OPTIONAL MATCH (s)-[:ADVANCED|INVOLVES]->(quest:Quest)
 OPTIONAL MATCH (s)-[:HAS_ACTIVITY]->(art:Artifact)
+OPTIONAL MATCH (art)-[:PART_OF]->(artQuest:Quest)
 OPTIONAL MATCH (s)-[:PRODUCED]->(pr:PR)
 RETURN
+  collect(DISTINCT {name:author.name, github:author.github})                  AS authors,
+  collect(DISTINCT {name:recipient.name, github:recipient.github})            AS recipients,
+  project.name                                                                AS project,
   collect(DISTINCT {id:prior.id, topic:prior.topic, author:priorAuthor.name}) AS implementsHandoff,
   collect(DISTINCT {id:later.id, topic:later.topic, author:laterAuthor.name}) AS implementedBy,
   collect(DISTINCT {id:cont.id,  topic:cont.topic,  author:contAuthor.name})  AS continues,
   collect(DISTINCT {id:quest.id, title:quest.title})                          AS quests,
-  collect(DISTINCT {id:art.id, title:art.title, type:art.type, path:art.path}) AS artifacts,
+  collect(DISTINCT {id:art.id, title:art.title, type:art.type})               AS artifacts,
+  collect(DISTINCT {artifactId:art.id, questId:artQuest.id, questTitle:artQuest.title}) AS artifactQuestLinks,
   collect(DISTINCT {id:pr.id, number:pr.number, title:pr.title, repo:pr.repo}) AS prs`;
 
   try {
@@ -177,24 +189,31 @@ function parseGraphResponse(raw) {
   const obj = {};
   fields.forEach((f, i) => { obj[f] = row[i]; });
 
-  // OPTIONAL MATCH + collect() emits sentinel {id: null, ...} entries — strip.
+  // OPTIONAL MATCH + collect() emits sentinel entries when nothing matched —
+  // filter them out by requiring at least one of the key fields to be set.
   const clean = (list, ...keys) => Array.isArray(list)
     ? list.filter(x => x && keys.some(k => x[k] != null))
     : [];
   return {
-    implementsHandoff: clean(obj.implementsHandoff, 'id'),
-    implementedBy:     clean(obj.implementedBy,     'id'),
-    continues:         clean(obj.continues,         'id'),
-    quests:            clean(obj.quests,            'id', 'title'),
-    artifacts:         clean(obj.artifacts,         'id', 'title', 'path'),
-    prs:               clean(obj.prs,               'id', 'number'),
+    authors:            clean(obj.authors,            'name', 'github'),
+    recipients:         clean(obj.recipients,         'name', 'github'),
+    project:            obj.project || null,
+    implementsHandoff:  clean(obj.implementsHandoff,  'id'),
+    implementedBy:      clean(obj.implementedBy,      'id'),
+    continues:          clean(obj.continues,          'id'),
+    quests:             clean(obj.quests,             'id', 'title'),
+    artifacts:          clean(obj.artifacts,          'id', 'title'),
+    artifactQuestLinks: clean(obj.artifactQuestLinks, 'artifactId', 'questId'),
+    prs:                clean(obj.prs,                'id', 'number'),
   };
 }
 
 function extractReferencedFiles(content, inputDir) {
   const attachments = [];
-  // Find backtick-wrapped paths that look like memory files
-  const refs = content.matchAll(/`(memory\/[^`]+\.md)`/g);
+  // Find backtick-wrapped paths that look like memory files (.md or .html).
+  // Must stay in sync with the corresponding pattern in lib/markdown.js and
+  // with bin/publish-references.sh.
+  const refs = content.matchAll(/`(memory\/[^`\s]+\.(?:md|html))`/g);
 
   // Resolve git root for file lookup
   let gitRoot = null;
@@ -218,7 +237,7 @@ function extractReferencedFiles(content, inputDir) {
     for (const candidate of candidates) {
       if (fs.existsSync(candidate)) {
         const fileContent = fs.readFileSync(candidate, 'utf-8');
-        const fileTitle = extractTitle(fileContent) || path.basename(refPath, '.md');
+        const fileTitle = extractTitle(fileContent) || path.basename(refPath, path.extname(refPath));
         attachments.push({ title: fileTitle, path: refPath, content: fileContent });
         break;
       }