@polygraph/codex-plugin 0.4.30 → 0.4.32

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "polygraph",
-  "version": "0.4.30",
+  "version": "0.4.32",
   "description": "AI agent skills and subagents for Polygraph multi-repo coordination",
   "author": {
     "name": "Narwhal Technologies Inc",

package/agents/polygraph-init-subagent.toml

@@ -69,7 +69,8 @@ This returns:
   - `name`: Repository name
   - `repository`: Full repo name (e.g., `org/repo`)
   - `provider`: VCS provider (e.g., `GITHUB`)
-  - `description`: AI-generated description of what the repository does (may be null)
+
+Candidate entries do not include repository descriptions. For natural-language discovery, pass the user's intent in `semanticQuery` so the service can apply semantic matching internally.
 
 ### Step 2: Select Relevant Repos
 
@@ -79,8 +80,8 @@ If `selectedRepoIds` or exact repo refs were provided by the main agent, use tho
 
 Otherwise, analyze the candidates using the `userContext` to determine which repos are relevant:
 
-1. Read each repo's `description`
-2. Match repo descriptions against the `userContext` to identify relevant repos
+1. Review each repo's `repository`, `name`, `provider`, and any relationship/filter metadata returned by the tool
+2. Match those fields and any requested filters against the `userContext` to identify relevant repos
 3. Select the repos that are relevant to the task
 4. When uncertain, include all candidates
 5. When the user described the task in natural language and the result is large, re-query with `semanticQuery` set to that description
@@ -129,16 +130,16 @@ Return a structured summary in this format:
 
 ### Repositories in this session
 
-| Repo | Repository ID | Description | Relationship |
-| --- | --- | --- | --- |
-| REPO_FULL_NAME | REPOSITORY_ID | DESCRIPTION | DIRECTION (distance: N) |
+| Repo | Repository ID | Relationship |
+| --- | --- | --- |
+| REPO_FULL_NAME | REPOSITORY_ID | DIRECTION (distance: N) |
 
 ### All Candidates Discovered
 (Only include this section if `list_repos` was called)
 
-| Repo | Repository ID | Description | Selected |
-| --- | --- | --- | --- |
-| REPO_FULL_NAME | REPOSITORY_ID | DESCRIPTION | Yes/No |
+| Repo | Repository ID | Selected |
+| --- | --- | --- |
+| REPO_FULL_NAME | REPOSITORY_ID | Yes/No |
 ```
 
 ## Important Notes

package/bin/polygraph-codex-plugin.mjs

@@ -13,839 +13,6 @@ import {
 import { homedir } from "node:os";
 import { dirname, join, relative, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
-
-// node_modules/smol-toml/dist/error.js
-function getLineColFromPtr(string, ptr) {
-  let lines = string.slice(0, ptr).split(/\r\n|\n|\r/g);
-  return [lines.length, lines.pop().length + 1];
-}
-function makeCodeBlock(string, line, column) {
-  let lines = string.split(/\r\n|\n|\r/g);
-  let codeblock = "";
-  let numberLen = (Math.log10(line + 1) | 0) + 1;
-  for (let i = line - 1; i <= line + 1; i++) {
-    let l = lines[i - 1];
-    if (!l)
-      continue;
-    codeblock += i.toString().padEnd(numberLen, " ");
-    codeblock += ":  ";
-    codeblock += l;
-    codeblock += "\n";
-    if (i === line) {
-      codeblock += " ".repeat(numberLen + column + 2);
-      codeblock += "^\n";
-    }
-  }
-  return codeblock;
-}
-var TomlError = class extends Error {
-  line;
-  column;
-  codeblock;
-  constructor(message, options) {
-    const [line, column] = getLineColFromPtr(options.toml, options.ptr);
-    const codeblock = makeCodeBlock(options.toml, line, column);
-    super(`Invalid TOML document: ${message}
-
-${codeblock}`, options);
-    this.line = line;
-    this.column = column;
-    this.codeblock = codeblock;
-  }
-};
-
-// node_modules/smol-toml/dist/util.js
-function isEscaped(str, ptr) {
-  let i = 0;
-  while (str[ptr - ++i] === "\\")
-    ;
-  return --i && i % 2;
-}
-function indexOfNewline(str, start = 0, end = str.length) {
-  let idx = str.indexOf("\n", start);
-  if (str[idx - 1] === "\r")
-    idx--;
-  return idx <= end ? idx : -1;
-}
-function skipComment(str, ptr) {
-  for (let i = ptr; i < str.length; i++) {
-    let c = str[i];
-    if (c === "\n")
-      return i;
-    if (c === "\r" && str[i + 1] === "\n")
-      return i + 1;
-    if (c < " " && c !== "	" || c === "\x7F") {
-      throw new TomlError("control characters are not allowed in comments", {
-        toml: str,
-        ptr
-      });
-    }
-  }
-  return str.length;
-}
-function skipVoid(str, ptr, banNewLines, banComments) {
-  let c;
-  while (1) {
-    while ((c = str[ptr]) === " " || c === "	" || !banNewLines && (c === "\n" || c === "\r" && str[ptr + 1] === "\n"))
-      ptr++;
-    if (banComments || c !== "#")
-      break;
-    ptr = skipComment(str, ptr);
-  }
-  return ptr;
-}
-function skipUntil(str, ptr, sep2, end, banNewLines = false) {
-  if (!end) {
-    ptr = indexOfNewline(str, ptr);
-    return ptr < 0 ? str.length : ptr;
-  }
-  for (let i = ptr; i < str.length; i++) {
-    let c = str[i];
-    if (c === "#") {
-      i = indexOfNewline(str, i);
-    } else if (c === sep2) {
-      return i + 1;
-    } else if (c === end || banNewLines && (c === "\n" || c === "\r" && str[i + 1] === "\n")) {
-      return i;
-    }
-  }
-  throw new TomlError("cannot find end of structure", {
-    toml: str,
-    ptr
-  });
-}
-function getStringEnd(str, seek) {
-  let first = str[seek];
-  let target = first === str[seek + 1] && str[seek + 1] === str[seek + 2] ? str.slice(seek, seek + 3) : first;
-  seek += target.length - 1;
-  do
-    seek = str.indexOf(target, ++seek);
-  while (seek > -1 && first !== "'" && isEscaped(str, seek));
-  if (seek > -1) {
-    seek += target.length;
-    if (target.length > 1) {
-      if (str[seek] === first)
-        seek++;
-      if (str[seek] === first)
-        seek++;
-    }
-  }
-  return seek;
-}
-
-// node_modules/smol-toml/dist/date.js
-var DATE_TIME_RE = /^(\d{4}-\d{2}-\d{2})?[T ]?(?:(\d{2}):\d{2}(?::\d{2}(?:\.\d+)?)?)?(Z|[-+]\d{2}:\d{2})?$/i;
-var TomlDate = class _TomlDate extends Date {
-  #hasDate = false;
-  #hasTime = false;
-  #offset = null;
-  constructor(date) {
-    let hasDate = true;
-    let hasTime = true;
-    let offset = "Z";
-    if (typeof date === "string") {
-      let match = date.match(DATE_TIME_RE);
-      if (match) {
-        if (!match[1]) {
-          hasDate = false;
-          date = `0000-01-01T${date}`;
-        }
-        hasTime = !!match[2];
-        hasTime && date[10] === " " && (date = date.replace(" ", "T"));
-        if (match[2] && +match[2] > 23) {
-          date = "";
-        } else {
-          offset = match[3] || null;
-          date = date.toUpperCase();
-          if (!offset && hasTime)
-            date += "Z";
-        }
-      } else {
-        date = "";
-      }
-    }
-    super(date);
-    if (!isNaN(this.getTime())) {
-      this.#hasDate = hasDate;
-      this.#hasTime = hasTime;
-      this.#offset = offset;
-    }
-  }
-  isDateTime() {
-    return this.#hasDate && this.#hasTime;
-  }
-  isLocal() {
-    return !this.#hasDate || !this.#hasTime || !this.#offset;
-  }
-  isDate() {
-    return this.#hasDate && !this.#hasTime;
-  }
-  isTime() {
-    return this.#hasTime && !this.#hasDate;
-  }
-  isValid() {
-    return this.#hasDate || this.#hasTime;
-  }
-  toISOString() {
-    let iso = super.toISOString();
-    if (this.isDate())
-      return iso.slice(0, 10);
-    if (this.isTime())
-      return iso.slice(11, 23);
-    if (this.#offset === null)
-      return iso.slice(0, -1);
-    if (this.#offset === "Z")
-      return iso;
-    let offset = +this.#offset.slice(1, 3) * 60 + +this.#offset.slice(4, 6);
-    offset = this.#offset[0] === "-" ? offset : -offset;
-    let offsetDate = new Date(this.getTime() - offset * 6e4);
-    return offsetDate.toISOString().slice(0, -1) + this.#offset;
-  }
-  static wrapAsOffsetDateTime(jsDate, offset = "Z") {
-    let date = new _TomlDate(jsDate);
-    date.#offset = offset;
-    return date;
-  }
-  static wrapAsLocalDateTime(jsDate) {
-    let date = new _TomlDate(jsDate);
-    date.#offset = null;
-    return date;
-  }
-  static wrapAsLocalDate(jsDate) {
-    let date = new _TomlDate(jsDate);
-    date.#hasTime = false;
-    date.#offset = null;
-    return date;
-  }
-  static wrapAsLocalTime(jsDate) {
-    let date = new _TomlDate(jsDate);
-    date.#hasDate = false;
-    date.#offset = null;
-    return date;
-  }
-};
-
-// node_modules/smol-toml/dist/primitive.js
-var INT_REGEX = /^((0x[0-9a-fA-F](_?[0-9a-fA-F])*)|(([+-]|0[ob])?\d(_?\d)*))$/;
-var FLOAT_REGEX = /^[+-]?\d(_?\d)*(\.\d(_?\d)*)?([eE][+-]?\d(_?\d)*)?$/;
-var LEADING_ZERO = /^[+-]?0[0-9_]/;
-var ESCAPE_REGEX = /^[0-9a-f]{2,8}$/i;
-var ESC_MAP = {
-  b: "\b",
-  t: "	",
-  n: "\n",
-  f: "\f",
-  r: "\r",
-  e: "\x1B",
-  '"': '"',
-  "\\": "\\"
-};
-function parseString(str, ptr = 0, endPtr = str.length) {
-  let isLiteral = str[ptr] === "'";
-  let isMultiline = str[ptr++] === str[ptr] && str[ptr] === str[ptr + 1];
-  if (isMultiline) {
-    endPtr -= 2;
-    if (str[ptr += 2] === "\r")
-      ptr++;
-    if (str[ptr] === "\n")
-      ptr++;
-  }
-  let tmp = 0;
-  let isEscape;
-  let parsed = "";
-  let sliceStart = ptr;
-  while (ptr < endPtr - 1) {
-    let c = str[ptr++];
-    if (c === "\n" || c === "\r" && str[ptr] === "\n") {
-      if (!isMultiline) {
-        throw new TomlError("newlines are not allowed in strings", {
-          toml: str,
-          ptr: ptr - 1
-        });
-      }
-    } else if (c < " " && c !== "	" || c === "\x7F") {
-      throw new TomlError("control characters are not allowed in strings", {
-        toml: str,
-        ptr: ptr - 1
-      });
-    }
-    if (isEscape) {
-      isEscape = false;
-      if (c === "x" || c === "u" || c === "U") {
-        let code = str.slice(ptr, ptr += c === "x" ? 2 : c === "u" ? 4 : 8);
-        if (!ESCAPE_REGEX.test(code)) {
-          throw new TomlError("invalid unicode escape", {
-            toml: str,
-            ptr: tmp
-          });
-        }
-        try {
-          parsed += String.fromCodePoint(parseInt(code, 16));
-        } catch {
-          throw new TomlError("invalid unicode escape", {
-            toml: str,
-            ptr: tmp
-          });
-        }
-      } else if (isMultiline && (c === "\n" || c === " " || c === "	" || c === "\r")) {
-        ptr = skipVoid(str, ptr - 1, true);
-        if (str[ptr] !== "\n" && str[ptr] !== "\r") {
-          throw new TomlError("invalid escape: only line-ending whitespace may be escaped", {
-            toml: str,
-            ptr: tmp
-          });
-        }
-        ptr = skipVoid(str, ptr);
-      } else if (c in ESC_MAP) {
-        parsed += ESC_MAP[c];
-      } else {
-        throw new TomlError("unrecognized escape sequence", {
-          toml: str,
-          ptr: tmp
-        });
-      }
-      sliceStart = ptr;
-    } else if (!isLiteral && c === "\\") {
-      tmp = ptr - 1;
-      isEscape = true;
-      parsed += str.slice(sliceStart, tmp);
-    }
-  }
-  return parsed + str.slice(sliceStart, endPtr - 1);
-}
-function parseValue(value, toml, ptr, integersAsBigInt) {
-  if (value === "true")
-    return true;
-  if (value === "false")
-    return false;
-  if (value === "-inf")
-    return -Infinity;
-  if (value === "inf" || value === "+inf")
-    return Infinity;
-  if (value === "nan" || value === "+nan" || value === "-nan")
-    return NaN;
-  if (value === "-0")
-    return integersAsBigInt ? 0n : 0;
-  let isInt = INT_REGEX.test(value);
-  if (isInt || FLOAT_REGEX.test(value)) {
-    if (LEADING_ZERO.test(value)) {
-      throw new TomlError("leading zeroes are not allowed", {
-        toml,
-        ptr
-      });
-    }
-    value = value.replace(/_/g, "");
-    let numeric = +value;
-    if (isNaN(numeric)) {
-      throw new TomlError("invalid number", {
-        toml,
-        ptr
-      });
-    }
-    if (isInt) {
-      if ((isInt = !Number.isSafeInteger(numeric)) && !integersAsBigInt) {
-        throw new TomlError("integer value cannot be represented losslessly", {
-          toml,
-          ptr
-        });
-      }
-      if (isInt || integersAsBigInt === true)
-        numeric = BigInt(value);
-    }
-    return numeric;
-  }
-  const date = new TomlDate(value);
-  if (!date.isValid()) {
-    throw new TomlError("invalid value", {
-      toml,
-      ptr
-    });
-  }
-  return date;
-}
-
-// node_modules/smol-toml/dist/extract.js
-function sliceAndTrimEndOf(str, startPtr, endPtr) {
-  let value = str.slice(startPtr, endPtr);
-  let commentIdx = value.indexOf("#");
-  if (commentIdx > -1) {
-    skipComment(str, commentIdx);
-    value = value.slice(0, commentIdx);
-  }
-  return [value.trimEnd(), commentIdx];
-}
-function extractValue(str, ptr, end, depth, integersAsBigInt) {
-  if (depth === 0) {
-    throw new TomlError("document contains excessively nested structures. aborting.", {
-      toml: str,
-      ptr
-    });
-  }
-  let c = str[ptr];
-  if (c === "[" || c === "{") {
-    let [value, endPtr2] = c === "[" ? parseArray(str, ptr, depth, integersAsBigInt) : parseInlineTable(str, ptr, depth, integersAsBigInt);
-    if (end) {
-      endPtr2 = skipVoid(str, endPtr2);
-      if (str[endPtr2] === ",")
-        endPtr2++;
-      else if (str[endPtr2] !== end) {
-        throw new TomlError("expected comma or end of structure", {
-          toml: str,
-          ptr: endPtr2
-        });
-      }
-    }
-    return [value, endPtr2];
-  }
-  let endPtr;
-  if (c === '"' || c === "'") {
-    endPtr = getStringEnd(str, ptr);
-    let parsed = parseString(str, ptr, endPtr);
-    if (end) {
-      endPtr = skipVoid(str, endPtr);
-      if (str[endPtr] && str[endPtr] !== "," && str[endPtr] !== end && str[endPtr] !== "\n" && str[endPtr] !== "\r") {
-        throw new TomlError("unexpected character encountered", {
-          toml: str,
-          ptr: endPtr
-        });
-      }
-      endPtr += +(str[endPtr] === ",");
-    }
-    return [parsed, endPtr];
-  }
-  endPtr = skipUntil(str, ptr, ",", end);
-  let slice = sliceAndTrimEndOf(str, ptr, endPtr - +(str[endPtr - 1] === ","));
-  if (!slice[0]) {
-    throw new TomlError("incomplete key-value declaration: no value specified", {
-      toml: str,
-      ptr
-    });
-  }
-  if (end && slice[1] > -1) {
-    endPtr = skipVoid(str, ptr + slice[1]);
-    endPtr += +(str[endPtr] === ",");
-  }
-  return [
-    parseValue(slice[0], str, ptr, integersAsBigInt),
-    endPtr
-  ];
-}
-
-// node_modules/smol-toml/dist/struct.js
-var KEY_PART_RE = /^[a-zA-Z0-9-_]+[ \t]*$/;
-function parseKey(str, ptr, end = "=") {
-  let dot = ptr - 1;
-  let parsed = [];
-  let endPtr = str.indexOf(end, ptr);
-  if (endPtr < 0) {
-    throw new TomlError("incomplete key-value: cannot find end of key", {
-      toml: str,
-      ptr
-    });
-  }
-  do {
-    let c = str[ptr = ++dot];
-    if (c !== " " && c !== "	") {
-      if (c === '"' || c === "'") {
-        if (c === str[ptr + 1] && c === str[ptr + 2]) {
-          throw new TomlError("multiline strings are not allowed in keys", {
-            toml: str,
-            ptr
-          });
-        }
-        let eos = getStringEnd(str, ptr);
-        if (eos < 0) {
-          throw new TomlError("unfinished string encountered", {
-            toml: str,
-            ptr
-          });
-        }
-        dot = str.indexOf(".", eos);
-        let strEnd = str.slice(eos, dot < 0 || dot > endPtr ? endPtr : dot);
-        let newLine = indexOfNewline(strEnd);
-        if (newLine > -1) {
-          throw new TomlError("newlines are not allowed in keys", {
-            toml: str,
-            ptr: ptr + dot + newLine
-          });
-        }
-        if (strEnd.trimStart()) {
-          throw new TomlError("found extra tokens after the string part", {
-            toml: str,
-            ptr: eos
-          });
-        }
-        if (endPtr < eos) {
-          endPtr = str.indexOf(end, eos);
-          if (endPtr < 0) {
-            throw new TomlError("incomplete key-value: cannot find end of key", {
-              toml: str,
-              ptr
-            });
-          }
-        }
-        parsed.push(parseString(str, ptr, eos));
-      } else {
-        dot = str.indexOf(".", ptr);
-        let part = str.slice(ptr, dot < 0 || dot > endPtr ? endPtr : dot);
-        if (!KEY_PART_RE.test(part)) {
-          throw new TomlError("only letter, numbers, dashes and underscores are allowed in keys", {
-            toml: str,
-            ptr
-          });
-        }
-        parsed.push(part.trimEnd());
-      }
-    }
-  } while (dot + 1 && dot < endPtr);
-  return [parsed, skipVoid(str, endPtr + 1, true, true)];
-}
-function parseInlineTable(str, ptr, depth, integersAsBigInt) {
-  let res = {};
-  let seen = /* @__PURE__ */ new Set();
-  let c;
-  ptr++;
-  while ((c = str[ptr++]) !== "}" && c) {
-    if (c === ",") {
-      throw new TomlError("expected value, found comma", {
-        toml: str,
-        ptr: ptr - 1
-      });
-    } else if (c === "#")
-      ptr = skipComment(str, ptr);
-    else if (c !== " " && c !== "	" && c !== "\n" && c !== "\r") {
-      let k;
-      let t = res;
-      let hasOwn = false;
-      let [key, keyEndPtr] = parseKey(str, ptr - 1);
-      for (let i = 0; i < key.length; i++) {
-        if (i)
-          t = hasOwn ? t[k] : t[k] = {};
-        k = key[i];
-        if ((hasOwn = Object.hasOwn(t, k)) && (typeof t[k] !== "object" || seen.has(t[k]))) {
-          throw new TomlError("trying to redefine an already defined value", {
-            toml: str,
-            ptr
-          });
-        }
-        if (!hasOwn && k === "__proto__") {
-          Object.defineProperty(t, k, { enumerable: true, configurable: true, writable: true });
-        }
-      }
-      if (hasOwn) {
-        throw new TomlError("trying to redefine an already defined value", {
-          toml: str,
-          ptr
-        });
-      }
-      let [value, valueEndPtr] = extractValue(str, keyEndPtr, "}", depth - 1, integersAsBigInt);
-      seen.add(value);
-      t[k] = value;
-      ptr = valueEndPtr;
-    }
-  }
-  if (!c) {
-    throw new TomlError("unfinished table encountered", {
-      toml: str,
-      ptr
-    });
-  }
-  return [res, ptr];
-}
-function parseArray(str, ptr, depth, integersAsBigInt) {
-  let res = [];
-  let c;
-  ptr++;
-  while ((c = str[ptr++]) !== "]" && c) {
-    if (c === ",") {
-      throw new TomlError("expected value, found comma", {
-        toml: str,
-        ptr: ptr - 1
-      });
-    } else if (c === "#")
-      ptr = skipComment(str, ptr);
-    else if (c !== " " && c !== "	" && c !== "\n" && c !== "\r") {
-      let e = extractValue(str, ptr - 1, "]", depth - 1, integersAsBigInt);
-      res.push(e[0]);
-      ptr = e[1];
-    }
-  }
-  if (!c) {
-    throw new TomlError("unfinished array encountered", {
-      toml: str,
-      ptr
-    });
-  }
-  return [res, ptr];
-}
-
-// node_modules/smol-toml/dist/parse.js
-function peekTable(key, table, meta, type) {
-  let t = table;
-  let m = meta;
-  let k;
-  let hasOwn = false;
-  let state;
-  for (let i = 0; i < key.length; i++) {
-    if (i) {
-      t = hasOwn ? t[k] : t[k] = {};
-      m = (state = m[k]).c;
-      if (type === 0 && (state.t === 1 || state.t === 2)) {
-        return null;
-      }
-      if (state.t === 2) {
-        let l = t.length - 1;
-        t = t[l];
-        m = m[l].c;
-      }
-    }
-    k = key[i];
-    if ((hasOwn = Object.hasOwn(t, k)) && m[k]?.t === 0 && m[k]?.d) {
-      return null;
-    }
-    if (!hasOwn) {
-      if (k === "__proto__") {
-        Object.defineProperty(t, k, { enumerable: true, configurable: true, writable: true });
-        Object.defineProperty(m, k, { enumerable: true, configurable: true, writable: true });
-      }
-      m[k] = {
-        t: i < key.length - 1 && type === 2 ? 3 : type,
-        d: false,
-        i: 0,
-        c: {}
-      };
-    }
-  }
-  state = m[k];
-  if (state.t !== type && !(type === 1 && state.t === 3)) {
-    return null;
-  }
-  if (type === 2) {
-    if (!state.d) {
-      state.d = true;
-      t[k] = [];
-    }
-    t[k].push(t = {});
-    state.c[state.i++] = state = { t: 1, d: false, i: 0, c: {} };
-  }
-  if (state.d) {
-    return null;
-  }
-  state.d = true;
-  if (type === 1) {
-    t = hasOwn ? t[k] : t[k] = {};
-  } else if (type === 0 && hasOwn) {
-    return null;
-  }
-  return [k, t, state.c];
-}
-function parse(toml, { maxDepth = 1e3, integersAsBigInt } = {}) {
-  let res = {};
-  let meta = {};
-  let tbl = res;
-  let m = meta;
-  for (let ptr = skipVoid(toml, 0); ptr < toml.length; ) {
-    if (toml[ptr] === "[") {
-      let isTableArray = toml[++ptr] === "[";
-      let k = parseKey(toml, ptr += +isTableArray, "]");
-      if (isTableArray) {
-        if (toml[k[1] - 1] !== "]") {
-          throw new TomlError("expected end of table declaration", {
-            toml,
-            ptr: k[1] - 1
-          });
-        }
-        k[1]++;
-      }
-      let p = peekTable(
-        k[0],
-        res,
-        meta,
-        isTableArray ? 2 : 1
-        /* Type.EXPLICIT */
-      );
-      if (!p) {
-        throw new TomlError("trying to redefine an already defined table or value", {
-          toml,
-          ptr
-        });
-      }
-      m = p[2];
-      tbl = p[1];
-      ptr = k[1];
-    } else {
-      let k = parseKey(toml, ptr);
-      let p = peekTable(
-        k[0],
-        tbl,
-        m,
-        0
-        /* Type.DOTTED */
-      );
-      if (!p) {
-        throw new TomlError("trying to redefine an already defined table or value", {
-          toml,
-          ptr
-        });
-      }
-      let v = extractValue(toml, k[1], void 0, maxDepth, integersAsBigInt);
-      p[1][p[0]] = v[0];
-      ptr = v[1];
-    }
-    ptr = skipVoid(toml, ptr, true);
-    if (toml[ptr] && toml[ptr] !== "\n" && toml[ptr] !== "\r") {
-      throw new TomlError("each key-value declaration must be followed by an end-of-line", {
-        toml,
-        ptr
-      });
-    }
-    ptr = skipVoid(toml, ptr);
-  }
-  return res;
-}
-
-// node_modules/smol-toml/dist/stringify.js
-var BARE_KEY = /^[a-z0-9-_]+$/i;
-function extendedTypeOf(obj) {
-  let type = typeof obj;
-  if (type === "object") {
-    if (Array.isArray(obj))
-      return "array";
-    if (obj instanceof Date)
-      return "date";
-  }
-  return type;
-}
-function isArrayOfTables(obj) {
-  for (let i = 0; i < obj.length; i++) {
-    if (extendedTypeOf(obj[i]) !== "object")
-      return false;
-  }
-  return obj.length != 0;
-}
-function formatString(s) {
-  return JSON.stringify(s).replace(/\x7f/g, "\\u007f");
-}
-function stringifyValue(val, type, depth, numberAsFloat) {
-  if (depth === 0) {
-    throw new Error("Could not stringify the object: maximum object depth exceeded");
-  }
-  if (type === "number") {
-    if (isNaN(val))
-      return "nan";
-    if (val === Infinity)
-      return "inf";
-    if (val === -Infinity)
-      return "-inf";
-    if (numberAsFloat && Number.isInteger(val))
-      return val.toFixed(1);
-    return val.toString();
-  }
-  if (type === "bigint" || type === "boolean") {
-    return val.toString();
-  }
-  if (type === "string") {
-    return formatString(val);
-  }
-  if (type === "date") {
-    if (isNaN(val.getTime())) {
-      throw new TypeError("cannot serialize invalid date");
-    }
-    return val.toISOString();
-  }
-  if (type === "object") {
-    return stringifyInlineTable(val, depth, numberAsFloat);
-  }
-  if (type === "array") {
-    return stringifyArray(val, depth, numberAsFloat);
-  }
-}
-function stringifyInlineTable(obj, depth, numberAsFloat) {
-  let keys = Object.keys(obj);
-  if (keys.length === 0)
-    return "{}";
-  let res = "{ ";
-  for (let i = 0; i < keys.length; i++) {
-    let k = keys[i];
-    if (i)
-      res += ", ";
-    res += BARE_KEY.test(k) ? k : formatString(k);
-    res += " = ";
-    res += stringifyValue(obj[k], extendedTypeOf(obj[k]), depth - 1, numberAsFloat);
-  }
-  return res + " }";
-}
-function stringifyArray(array, depth, numberAsFloat) {
-  if (array.length === 0)
-    return "[]";
-  let res = "[ ";
-  for (let i = 0; i < array.length; i++) {
-    if (i)
-      res += ", ";
-    if (array[i] === null || array[i] === void 0) {
-      throw new TypeError("arrays cannot contain null or undefined values");
-    }
-    res += stringifyValue(array[i], extendedTypeOf(array[i]), depth - 1, numberAsFloat);
-  }
-  return res + " ]";
-}
-function stringifyArrayTable(array, key, depth, numberAsFloat) {
-  if (depth === 0) {
-    throw new Error("Could not stringify the object: maximum object depth exceeded");
-  }
-  let res = "";
-  for (let i = 0; i < array.length; i++) {
-    res += `${res && "\n"}[[${key}]]
-`;
-    res += stringifyTable(0, array[i], key, depth, numberAsFloat);
-  }
-  return res;
-}
-function stringifyTable(tableKey, obj, prefix, depth, numberAsFloat) {
-  if (depth === 0) {
-    throw new Error("Could not stringify the object: maximum object depth exceeded");
-  }
-  let preamble = "";
-  let tables = "";
-  let keys = Object.keys(obj);
-  for (let i = 0; i < keys.length; i++) {
-    let k = keys[i];
-    if (obj[k] !== null && obj[k] !== void 0) {
-      let type = extendedTypeOf(obj[k]);
-      if (type === "symbol" || type === "function") {
-        throw new TypeError(`cannot serialize values of type '${type}'`);
-      }
-      let key = BARE_KEY.test(k) ? k : formatString(k);
-      if (type === "array" && isArrayOfTables(obj[k])) {
-        tables += (tables && "\n") + stringifyArrayTable(obj[k], prefix ? `${prefix}.${key}` : key, depth - 1, numberAsFloat);
-      } else if (type === "object") {
-        let tblKey = prefix ? `${prefix}.${key}` : key;
-        tables += (tables && "\n") + stringifyTable(tblKey, obj[k], tblKey, depth - 1, numberAsFloat);
-      } else {
-        preamble += key;
-        preamble += " = ";
-        preamble += stringifyValue(obj[k], type, depth, numberAsFloat);
-        preamble += "\n";
-      }
-    }
-  }
-  if (tableKey && (preamble || !tables))
-    preamble = preamble ? `[${tableKey}]
-${preamble}` : `[${tableKey}]`;
-  return preamble && tables ? `${preamble}
-${tables}` : preamble || tables;
-}
-function stringify(obj, { maxDepth = 1e3, numbersAsFloat = false } = {}) {
-  if (extendedTypeOf(obj) !== "object") {
-    throw new TypeError("stringify can only be called with an object");
-  }
-  let str = stringifyTable(0, obj, "", maxDepth, numbersAsFloat);
-  if (str[str.length - 1] !== "\n")
-    return str + "\n";
-  return str;
-}
-
-// source/codex/lib/installer.mjs
 var PLUGIN_NAME = "polygraph";
 var PLUGIN_ID = "polygraph@polygraph-plugins";
 var MARKETPLACE_NAME = "polygraph-plugins";
@@ -861,22 +28,9 @@ function resolveCodexHome(env = process.env) {
   const userHome = env.HOME?.trim() || homedir();
   return join(resolve(expandHome(userHome, env)), ".codex");
 }
-function getConfigPath(codexHome) {
-  return join(codexHome, "config.toml");
-}
 function getAgentsPath(codexHome) {
   return join(codexHome, "agents");
 }
-function getCacheRoot(codexHome, version) {
-  const base = join(
-    codexHome,
-    "plugins",
-    "cache",
-    MARKETPLACE_NAME,
-    PLUGIN_NAME
-  );
-  return version ? join(base, version) : base;
-}
 function resolveUserHome(env = process.env) {
   const userHome = env.HOME?.trim() || homedir();
   return resolve(expandHome(userHome, env));
@@ -917,23 +71,6 @@ function loadPackageMetadata(packageRoot) {
     version: packageJson.version
   };
 }
-function mirrorCodexPluginCache({ codexHome, packageRoot, packageJson, version }) {
-  if (!existsSync(codexHome)) {
-    return null;
-  }
-  const pluginCacheRoot = getCacheRoot(codexHome);
-  if (existsSync(pluginCacheRoot)) {
-    for (const entry of readdirSync(pluginCacheRoot)) {
-      rmSync(join(pluginCacheRoot, entry), { recursive: true, force: true });
-    }
-  }
-  const versionedCachePath = getCacheRoot(codexHome, version);
-  mkdirSync(versionedCachePath, { recursive: true });
-  for (const relativePath of getPackagePayloadPaths(packageRoot, packageJson)) {
-    copyRelativeEntry(packageRoot, versionedCachePath, relativePath);
-  }
-  return versionedCachePath;
-}
 function installPlugin({
   packageRoot,
   env = process.env,
@@ -945,7 +82,6 @@ function installPlugin({
   const { packageJson, version } = loadPackageMetadata(packageRoot);
   const codexHome = resolveCodexHome(env);
   const userHome = resolveUserHome(env);
-  const configPath = getConfigPath(codexHome);
   const agentsPath = getAgentsPath(codexHome);
   const marketplacePath = getMarketplacePath(userHome);
   const pluginPath = getPluginInstallPath(userHome);
@@ -980,19 +116,12 @@ function installPlugin({
     }
     copied = true;
   }
-  const configChanged = enablePluginInConfig(configPath);
   const agentsChanged = installCodexAgents({ packageRoot, agentsPath });
   const marketplaceChanged = enablePluginInMarketplace({
     marketplacePath,
     pluginPath,
     userHome
   });
-  const codexCachePath = mirrorCodexPluginCache({
-    codexHome,
-    packageRoot,
-    packageJson,
-    version
-  });
   return {
     ok: true,
     action: "install",
@@ -1001,14 +130,11 @@ function installPlugin({
     codexHome,
     agentsPath,
     pluginPath,
-    configPath,
     marketplacePath,
-    codexCachePath,
     copied,
     overwritten: installAlreadyPresent && force,
     pluginUpdated: installAlreadyPresent && versionMismatch && !force,
     previousVersion,
-    configChanged,
     agentsChanged,
     marketplaceChanged
   };
@@ -1020,22 +146,17 @@ function checkInstall({ packageRoot, env = process.env } = {}) {
   }
   const codexHome = resolveCodexHome(env);
   const userHome = resolveUserHome(env);
-  const configPath = getConfigPath(codexHome);
   const agentsPath = getAgentsPath(codexHome);
   const marketplacePath = getMarketplacePath(userHome);
   const pluginPath = getPluginInstallPath(userHome);
   const pluginInstalled = isValidInstalledPluginDir(pluginPath);
-  const configEnabled = isPluginEnabled(configPath);
   const agentsInstalled = packageRoot ? areCodexAgentsInstalled({ packageRoot, agentsPath }) : hasDefaultCodexAgents(agentsPath);
   const marketplaceConfigured = isPluginConfiguredInMarketplace({
     marketplacePath,
     userHome,
     pluginPath
   });
-  const ok = pluginInstalled && configEnabled && agentsInstalled && marketplaceConfigured;
-  const codexHomeExists = existsSync(codexHome);
-  const codexCachePath = codexHomeExists && version ? getCacheRoot(codexHome, version) : null;
-  const codexCacheMirrored = codexCachePath !== null ? isCodexCacheCurrent({ cachePath: codexCachePath, pluginPath }) : null;
+  const ok = pluginInstalled && agentsInstalled && marketplaceConfigured;
   return {
     ok,
     action: "check",
@@ -1043,43 +164,12 @@ function checkInstall({ packageRoot, env = process.env } = {}) {
     codexHome,
     agentsPath,
     pluginPath,
-    configPath,
     marketplacePath,
-    codexCachePath,
     pluginInstalled,
-    configEnabled,
     agentsInstalled,
-    marketplaceConfigured,
-    codexCacheMirrored
+    marketplaceConfigured
   };
 }
-function enablePluginInConfig(configPath) {
-  const config = readTomlFile(configPath);
-  if (config.plugins !== void 0 && !isPlainObject(config.plugins)) {
-    throw new Error(
-      `Expected plugins table in ${configPath} to be a TOML table`
-    );
-  }
-  const plugins = config.plugins ?? {};
-  const pluginConfig = plugins[PLUGIN_ID];
-  if (pluginConfig !== void 0 && !isPlainObject(pluginConfig)) {
-    throw new Error(
-      `Expected plugins."${PLUGIN_ID}" in ${configPath} to be a TOML table`
-    );
-  }
-  const wasEnabled = pluginConfig?.enabled === true;
-  plugins[PLUGIN_ID] = { ...pluginConfig ?? {}, enabled: true };
-  config.plugins = plugins;
-  writeTomlFile(configPath, config);
-  return !wasEnabled;
-}
-function isPluginEnabled(configPath) {
-  if (!existsSync(configPath)) {
-    return false;
-  }
-  const config = readTomlFile(configPath);
-  return config.plugins?.[PLUGIN_ID]?.enabled === true;
-}
 function getPackagePayloadPaths(packageRoot, packageJson) {
   const relativePaths = new Set(packageJson.files ?? []);
   relativePaths.add("package.json");
@@ -1209,25 +299,6 @@ function isPluginConfiguredInMarketplace({
   const configuredPath = resolve(userHome, pluginEntry.source.path);
   return configuredPath === resolve(pluginPath);
 }
-function readTomlFile(path) {
-  if (!existsSync(path)) {
-    return {};
-  }
-  const raw = readFileSync(path, "utf8");
-  if (raw.trim() === "") {
-    return {};
-  }
-  const parsed = parse(raw);
-  if (!isPlainObject(parsed)) {
-    throw new Error(`Expected TOML document at ${path} to parse to an object`);
-  }
-  return parsed;
-}
-function writeTomlFile(path, value) {
-  mkdirSync(dirname(path), { recursive: true });
-  writeFileSync(path, `${stringify(value).trimEnd()}
-`);
-}
 function readJsonFile(path, fallbackValue) {
   if (!existsSync(path)) {
     return fallbackValue;
@@ -1239,45 +310,6 @@ function writeJsonFile(path, value) {
   writeFileSync(path, `${JSON.stringify(value, null, 2)}
 `);
 }
-function isCodexCacheCurrent({ cachePath, pluginPath }) {
-  if (!existsSync(cachePath) || !existsSync(pluginPath)) {
-    return false;
-  }
-  return directoriesMatch(pluginPath, cachePath);
-}
-function directoriesMatch(aDir, bDir) {
-  if (!existsSync(aDir) || !existsSync(bDir)) {
-    return false;
-  }
-  const aEntries = readdirSync(aDir, { withFileTypes: true }).sort(
-    (x, y) => x.name < y.name ? -1 : x.name > y.name ? 1 : 0
-  );
-  const bEntries = readdirSync(bDir, { withFileTypes: true }).sort(
-    (x, y) => x.name < y.name ? -1 : x.name > y.name ? 1 : 0
-  );
-  if (aEntries.length !== bEntries.length) {
-    return false;
-  }
-  for (let i = 0; i < aEntries.length; i++) {
-    const a = aEntries[i];
-    const b = bEntries[i];
-    if (a.name !== b.name || a.isDirectory() !== b.isDirectory()) {
-      return false;
-    }
-    if (a.isDirectory()) {
-      if (!directoriesMatch(join(aDir, a.name), join(bDir, b.name))) {
-        return false;
-      }
-    } else {
-      const aContent = readFileSync(join(aDir, a.name));
-      const bContent = readFileSync(join(bDir, b.name));
-      if (!aContent.equals(bContent)) {
-        return false;
-      }
-    }
-  }
-  return true;
-}
 function isValidInstalledPluginDir(candidatePath) {
   const pluginManifestPath = join(
     candidatePath,
@@ -1326,7 +358,14 @@ function isPlainObject(value) {
 var usage = `Usage:
   npx @polygraph/codex-plugin
   npx @polygraph/codex-plugin install [--force] [--json]
-  npx @polygraph/codex-plugin check [--json]`;
+  npx @polygraph/codex-plugin check [--json]
+
+The install command materializes the plugin payload so that codex's official
+plugin system can pick it up. After running install, run:
+
+  codex plugin add polygraph@polygraph-plugins
+
+to have codex register and enable the plugin in its own config.`;
 async function main() {
   const args = process.argv.slice(2);
   let command = "install";
@@ -1362,26 +401,24 @@ ${usage}`);
     console.log(JSON.stringify(result, null, 2));
   } else if (command === "check") {
     if (result.ok) {
-      console.log(`Polygraph Codex plugin is enabled.`);
+      console.log(`Polygraph Codex plugin is materialized.`);
       console.log(`Plugin path: ${result.pluginPath}`);
       console.log(`Agents: ${result.agentsPath}`);
-      console.log(`Config: ${result.configPath}`);
       console.log(`Marketplace: ${result.marketplacePath}`);
     } else {
       const pluginState = result.pluginInstalled ? "plugin files present" : "plugin files not present";
-      const configState = result.configEnabled ? "plugin enabled in config" : "plugin not enabled in config";
       const agentsState = result.agentsInstalled ? "agents installed" : "agents not installed";
       const marketplaceState = result.marketplaceConfigured ? "plugin present in marketplace" : "plugin not present in marketplace";
       console.error(
-        `Polygraph Codex plugin check failed: ${pluginState}; ${configState}; ${agentsState}; ${marketplaceState}.`
+        `Polygraph Codex plugin check failed: ${pluginState}; ${agentsState}; ${marketplaceState}.`
       );
     }
   } else {
-    console.log(`Installed Polygraph Codex plugin ${result.version}.`);
+    console.log(`Materialized Polygraph Codex plugin ${result.version}.`);
     console.log(`Plugin path: ${result.pluginPath}`);
     console.log(`Agents: ${result.agentsPath}`);
-    console.log(`Config: ${result.configPath}`);
     console.log(`Marketplace: ${result.marketplacePath}`);
+    console.log(`Next step: codex plugin add ${result.plugin}`);
   }
   if (command === "check" && !result.ok) {
     process.exitCode = 1;
@@ -1392,42 +429,3 @@ main().catch((error) => {
   console.error(`polygraph-codex-plugin failed: ${message}`);
   process.exitCode = 1;
 });
-/*! Bundled license information:
-
-smol-toml/dist/error.js:
-smol-toml/dist/util.js:
-smol-toml/dist/date.js:
-smol-toml/dist/primitive.js:
-smol-toml/dist/extract.js:
-smol-toml/dist/struct.js:
-smol-toml/dist/parse.js:
-smol-toml/dist/stringify.js:
-smol-toml/dist/index.js:
-  (*!
-   * Copyright (c) Squirrel Chat et al., All rights reserved.
-   * SPDX-License-Identifier: BSD-3-Clause
-   *
-   * Redistribution and use in source and binary forms, with or without
-   * modification, are permitted provided that the following conditions are met:
-   *
-   * 1. Redistributions of source code must retain the above copyright notice, this
-   *    list of conditions and the following disclaimer.
-   * 2. Redistributions in binary form must reproduce the above copyright notice,
-   *    this list of conditions and the following disclaimer in the
-   *    documentation and/or other materials provided with the distribution.
-   * 3. Neither the name of the copyright holder nor the names of its contributors
-   *    may be used to endorse or promote products derived from this software without
-   *    specific prior written permission.
-   *
-   * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
-   * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
-   * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
-   * DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
-   * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
-   * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
-   * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
-   * CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
-   * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
-   * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
-   *)
-*/

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@polygraph/codex-plugin",
-  "version": "0.4.30",
+  "version": "0.4.32",
   "description": "AI agent skills and subagents for Polygraph multi-repo coordination",
   "license": "UNLICENSED",
   "private": false,

package/skills/polygraph/SKILL.md

@@ -29,7 +29,7 @@ Polygraph functionality is available via both MCP tools and CLI commands. Use wh
 
 | MCP Tool | CLI Equivalent | Description |
 | --- | --- | --- |
-| `list_repos` | `polygraph repo list` | Discover candidate repositories. |
+| `list_repos` | `polygraph repo list` | Discover candidate repositories. Candidate entries do not include repository descriptions; use `semanticQuery` for natural-language discovery. |
 | `start_session` | `polygraph session start --repo <ids>` | Initialize a Polygraph session with selected repositories |
 | `spawn_agent` | — | Start a new child task or send a follow-up to an active task in another repository. Input: `{ sessionId, repo, instruction, context? }`. Output: `{ taskId, message, status: 'delegated' }`. Follow-up routing is automatic: if the repo already has an active child task, the instruction is delivered to it as a follow-up message; otherwise a new child run starts. A repo has at most one active child at a time. A session resume or reconstruction is read-only context restoration; after resuming, do not use `spawn_agent` to continue changes unless the user explicitly asks for changes. |
 | `show_agent` | — | Poll flat per-child status for the session. Output: `{ children: PolygraphChildStatusItem[] }` where each item exposes `repositoryId`, `repoFullName`, `status`, `lastOutputLines`, `durationMs`, `instruction`, `agentType?`, `inputRequiredQuestion?`. `status` is an AcpRunStatus: `'created' \| 'in-progress' \| 'input-required' \| 'permission-required' \| 'completed' \| 'failed' \| 'cancelled'` (British double-L on `'cancelled'`). `inputRequiredQuestion` is populated only when `status === 'input-required'`. |
@@ -306,27 +306,9 @@ push_branch(
 
 ### Session Description Policy
 
-`description` is user-facing Polygraph session context.
+`description` is user-facing Polygraph session context. It is required for `push_branch`, `create_pr`, and `associate_pr`, and is the primary input to `update_session` (`mark_pr_ready` does not take a description).
 
-`description` is required for `push_branch`, `create_pr`, and `associate_pr`, and is the primary input to `update_session` (which takes `title` and/or `description`). (`mark_pr_ready` does not take a description.) Use the canonical structured format:
-
-```text
-Goal: <what the session is trying to accomplish>
-
-Current Progress: <what has been completed so far, including PR/session state when relevant>
-
-What Worked: <important decisions, approaches, or constraints that future agents should preserve>
-
-Next Steps: <clear next implementation steps>
-```
-
-- Do not use a one-line feature summary for final handoff or PR creation in a multi-repo session.
-- Keep it concise but durable for a future resumed agent.
-- Prefer high-level state over file-by-file changelogs.
-- Mention unresolved decisions or risks when they matter.
-- In `Next Steps`, include only next implementation steps. Do not list routine operational steps such as pushing branches, watching CI, or marking PRs ready.
-
-> **Tip (optional):** The Polygraph UI renders fenced ` ```mermaid ` blocks in the session description as diagrams. If a small diagram would genuinely clarify the session state — for example, cross-repo relationships or a sequence of changes — you may include one. Plain text remains the norm; diagrams are never required.
+**Whenever you write or update a session description, read [`reference/session-description.md`](reference/session-description.md) first.** That reference file holds the full policy: the canonical Markdown-heading template (`## Goal` / `## Current progress` / `## What worked` / `## Next steps`), the dual-audience guidance (humans in the web UI now, agents reconstructing history later), and the formatting building blocks the app renders (callouts, tables, mermaid, links, `link_reference`).
 
 ### 3. Create Draft PRs
 
@@ -636,15 +618,11 @@ get_ci_logs(
 
 ### Update Session Description
 
-Use this when the user asks to summarize progress, update the session description, capture the current state.
+Use this when the user asks to summarize progress, update the session description, or capture the current state.
 
-Before writing:
-- Read the current session details.
-- Consider the current conversation, child-agent results, PRs, pushed branches, validation, and unresolved decisions.
-- If appending a new item, read the current/latest description first and write the full replacement description with the existing items plus the new item.
-- If updating or replacing the existing last item, write the resulting state directly.
+Read [`reference/session-description.md`](reference/session-description.md) for the full update procedure (what to read before writing, how to append vs. replace) and the canonical Markdown-heading format. Then call `update_session` with the resulting summary as `description`.
 
-Write the description using the canonical structured format in the Session Description Policy. Then call `update_session` with the resulting summary as `description`.
+Be liberal about updating the session description when you make changes that affect the scope of the session, how logic flows between repos, or anything else important for posterity. Avoid updating it for small implementation details that are not relevant outside of this session. An up-to-date session description matters for maintainability.
 
 ### Print Polygraph Session Details
 

package/skills/polygraph/reference/session-description.md

@@ -0,0 +1,111 @@
+# Session Description Reference
+
+## Session Description Policy
+
+`description` is user-facing Polygraph session context.
+
+`description` is required for `push_branch`, `create_pr`, and `associate_pr`, and is the primary input to `update_session` (which takes `title` and/or `description`). (`mark_pr_ready` does not take a description.) The Polygraph web app renders the description as Markdown, so use real Markdown headings — not flat `Label:` lines. Use the canonical structured format:
+
+```markdown
+## Goal
+
+<what the session is trying to accomplish>
+
+## Current progress
+
+<what has been completed so far, including PR/session state when relevant>
+
+## What worked
+
+<important decisions, approaches, or constraints that future agents should preserve>
+
+## Next steps
+
+<clear next implementation steps>
+```
+
+- Do not use a one-line feature summary for final handoff or PR creation in a multi-repo session.
+- Keep it concise but durable for a future resumed agent.
+- Prefer high-level state over file-by-file changelogs.
+- Mention unresolved decisions or risks when they matter.
+- In `Next steps`, include only next implementation steps. Do not list routine operational steps such as pushing branches, watching CI, or marking PRs ready.
+
+## Dual audience: humans now, agents later
+
+The description has two readers, and you must write for both:
+
+1. **Humans, in the web UI** — this is the primary surface. The app renders the description as Markdown for people scanning session state.
+2. **Agents, later** — the description is also read back by agents reconstructing session history (for example, on resume). They may not have the original working tree, branch, or local environment available.
+
+Because of the second audience, write **durably**:
+
+- Avoid ephemeral or local references (paths, ports, in-progress scratch state) that won't mean anything to a later reader.
+- Don't assume the original working tree is available — describe *what* changed and *why* at a level that survives without the diff in front of you.
+- Capture decisions and constraints, not just a snapshot of the current terminal.
+
+## Formatting building blocks
+
+Plain text (headings + prose + lists) remains the norm. The blocks below are available when they genuinely add clarity — reach for them only when they earn their place.
+
+### Headings, emphasis, lists
+
+Use the `##` headings from the canonical template. Use **bold**/*italic* for emphasis, and bullet or numbered lists for enumerations. Keep nesting shallow.
+
+### Callouts (GitHub alert syntax)
+
+The app maps each callout to a status color, so pick the right type:
+
+- `> [!WARNING]` / `> [!CAUTION]` — risky migrations, destructive operations, or **required manual steps** a reader must not miss.
+- `> [!NOTE]` / `> [!IMPORTANT]` — context, rationale, or a key constraint worth highlighting.
+- `> [!TIP]` — an optional helpful pointer.
+
+```markdown
+> [!WARNING]
+> The auth migration must run before deploying the API repo, or existing sessions are invalidated.
+```
+
+### Tables (GFM)
+
+Use a GitHub-Flavored Markdown table only for genuinely tabular data. The polygraph UI already shows per-PR state so avoid that. 
+
+```markdown
+| Repo        |  Change Type        |
+| ----------- |  ------------------ |
+| org/api     |  api functionality  |
+| org/web     |  text-only          |
+```
+
+### Mermaid diagrams
+
+The app renders fenced ` ```mermaid ` blocks as diagrams. Use one only when it genuinely clarifies session state. Good uses:
+
+- Control or data flow between logic pieces across repos or system components.
+- A sequence of changes, or migration order.
+- A state machine.
+
+> [!IMPORTANT]
+> Do NOT redraw the cross-repo dependency / repository graph. The app already renders the repo-relationship graph for every session, so a repo-relationship diagram in the description is redundant.
+
+Plain text remains the norm; diagrams are optional and never required.
+
+### Code blocks and task lists
+
+Use fenced code blocks for commands, signatures, or short snippets. Use task lists (`- [ ]` / `- [x]`) when tracking discrete remaining work items.
+
+### Links
+
+- Prefer durable external URLs (e.g. GitHub PRs/issues, Linear tickets).
+- Do NOT put local or dev links in the description: `localhost`, `127.0.0.1`, and `file://` URLs do not resolve in the UI and are useless to later readers.
+- Do NOT put repo-relative file paths (`./foo.ts`, `../bar`) as links — they don't resolve in the UI.
+- To attach supplementary references (PRs, issues, other Polygraph sessions, Linear tickets), use the `link_reference` tool instead of inline links. `link_reference` is **supplementary** to the description, not a replacement for it.
+
+## Updating the session description
+
+Before writing:
+
+- Read the current session details.
+- Consider the current conversation, child-agent results, PRs, pushed branches, validation, and unresolved decisions.
+- If appending a new item, read the current/latest description first and write the full replacement description with the existing items plus the new item.
+- If updating or replacing the existing last item, write the resulting state directly.
+
+Write the description using the canonical structured format above. Then call `update_session` or one of the other tools like `create_pr` that take a description as input.