brainjar 0.3.747 → 0.3.976

package/brainjar.js

@@ -107,7 +107,7 @@ var CLI_VERSION, CACHE, DAY;
 var init_version_check = __esm({
   "packages/cli/src/version-check.ts"() {
     "use strict";
-    CLI_VERSION = "0.3.747";
+    CLI_VERSION = "0.3.976";
     CACHE = path.join(os.homedir(), ".brainjar", "version-check.json");
     DAY = 864e5;
   }
@@ -1344,6 +1344,8 @@ var require_defaults = __commonJS({
       idleTimeoutMillis: 3e4,
       client_encoding: "",
       ssl: false,
+      // SSL negotiation style: 'postgres' (traditional SSLRequest) or 'direct'
+      sslnegotiation: void 0,
       application_name: void 0,
       fallback_application_name: void 0,
       options: void 0,
@@ -1481,20 +1483,20 @@ var require_utils = __commonJS({
       }
       return config;
     }
-    var escapeIdentifier2 = function(str) {
-      return '"' + str.replace(/"/g, '""') + '"';
+    var escapeIdentifier2 = function(str2) {
+      return '"' + str2.replace(/"/g, '""') + '"';
     };
-    var escapeLiteral2 = function(str) {
+    var escapeLiteral2 = function(str2) {
       let hasBackslash = false;
       let escaped = "'";
-      if (str == null) {
+      if (str2 == null) {
         return "''";
       }
-      if (typeof str !== "string") {
+      if (typeof str2 !== "string") {
         return "''";
       }
-      for (let i = 0; i < str.length; i++) {
-        const c = str[i];
+      for (let i = 0; i < str2.length; i++) {
+        const c = str2[i];
         if (c === "'") {
           escaped += c + c;
         } else if (c === "\\") {
@@ -1909,22 +1911,22 @@ var require_type_overrides = __commonJS({
 var require_pg_connection_string = __commonJS({
   "node_modules/pg-connection-string/index.js"(exports, module) {
     "use strict";
-    function parse(str, options = {}) {
-      if (str.charAt(0) === "/") {
-        const config2 = str.split(" ");
+    function parse(str2, options = {}) {
+      if (str2.charAt(0) === "/") {
+        const config2 = str2.split(" ");
         return { host: config2[0], database: config2[1] };
       }
       const config = /* @__PURE__ */ Object.create(null);
       let result;
       let dummyHost = false;
-      if (/ |%[^a-f0-9]|%[a-f0-9][^a-f0-9]/i.test(str)) {
-        str = encodeURI(str).replace(/%25(\d\d)/g, "%$1");
+      if (/ |%[^a-f0-9]|%[a-f0-9][^a-f0-9]/i.test(str2)) {
+        str2 = encodeURI(str2).replace(/%25(\d\d)/g, "%$1");
       }
       try {
         try {
-          result = new URL(str, "postgres://base");
+          result = new URL(str2, "postgres://base");
         } catch (e) {
-          result = new URL(str.replace("@/", "@___DUMMY___/"), "postgres://base");
+          result = new URL(str2.replace("@/", "@___DUMMY___/"), "postgres://base");
           dummyHost = true;
         }
       } catch (err) {
@@ -1942,11 +1944,11 @@ var require_pg_connection_string = __commonJS({
         config.client_encoding = result.searchParams.get("encoding");
         return config;
       }
-      const hostname = dummyHost ? "" : result.hostname;
+      const hostname2 = dummyHost ? "" : result.hostname;
       if (!config.host) {
-        config.host = decodeURIComponent(hostname);
-      } else if (hostname && /^%2f/i.test(hostname)) {
-        result.pathname = hostname + result.pathname;
+        config.host = decodeURIComponent(hostname2);
+      } else if (hostname2 && /^%2f/i.test(hostname2)) {
+        result.pathname = hostname2 + result.pathname;
       }
       if (!config.port) {
         config.port = result.port;
@@ -1962,6 +1964,9 @@ var require_pg_connection_string = __commonJS({
       if (config.sslcert || config.sslkey || config.sslrootcert || config.sslmode) {
         config.ssl = {};
       }
+      if (config.sslnegotiation === "direct" && config.ssl === void 0) {
+        config.ssl = true;
+      }
       const fs = config.sslcert || config.sslkey || config.sslrootcert ? __require("fs") : null;
       if (config.sslcert) {
         config.ssl.cert = fs.readFileSync(config.sslcert).toString();
@@ -2067,8 +2072,8 @@ var require_pg_connection_string = __commonJS({
       }, /* @__PURE__ */ Object.create(null));
       return poolConfig;
     }
-    function parseIntoClientConfig(str) {
-      return toClientConfig(parse(str));
+    function parseIntoClientConfig(str2) {
+      return toClientConfig(parse(str2));
     }
     function deprecatedSslModeWarning(sslmode) {
       if (!deprecatedSslModeWarning.warned && typeof process !== "undefined" && process.emitWarning) {
@@ -2167,6 +2172,15 @@ var require_connection_parameters = __commonJS({
             enumerable: false
           });
         }
+        this.sslnegotiation = val("sslnegotiation", config, "PGSSLNEGOTIATION");
+        if (this.sslnegotiation !== void 0 && this.sslnegotiation !== "postgres" && this.sslnegotiation !== "direct") {
+          throw new Error(
+            `Invalid sslnegotiation value: "${this.sslnegotiation}". Valid values are "postgres" and "direct".`
+          );
+        }
+        if (this.sslnegotiation === "direct" && !this.ssl) {
+          throw new Error("sslnegotiation=direct requires SSL to be enabled");
+        }
         this.client_encoding = val("client_encoding", config);
         this.replication = val("replication", config);
         this.isDomainSocket = !(this.host || "").indexOf("/");
@@ -2205,6 +2219,7 @@ var require_connection_parameters = __commonJS({
         add(params, ssl, "sslkey");
         add(params, ssl, "sslcert");
         add(params, ssl, "sslrootcert");
+        add(params, this, "sslnegotiation");
         if (this.database) {
           params.push("dbname=" + quoteParamValue(this.database));
         }
@@ -2446,7 +2461,7 @@ var require_query = __commonJS({
         if (typeof this.text !== "string" && typeof this.name !== "string") {
           return new Error("A query must have either text or a name. Supplying neither is unsupported.");
         }
-        const previous = connection.parsedStatements[this.name];
+        const previous = connection.parsedStatements[this.name] || connection.submittedNamedStatements[this.name];
         if (this.text && previous && this.text !== previous) {
           return new Error(`Prepared statements must be unique - '${this.name}' was used for a different statement`);
         }
@@ -2466,7 +2481,7 @@ var require_query = __commonJS({
         return null;
       }
       hasBeenParsed(connection) {
-        return this.name && connection.parsedStatements[this.name];
+        return this.name && (connection.parsedStatements[this.name] || connection.submittedNamedStatements[this.name]);
       }
       handlePortalSuspended(connection) {
         this._getRows(connection, this.rows);
@@ -2490,6 +2505,9 @@ var require_query = __commonJS({
             name: this.name,
             types: this.types
           });
+          if (this.name) {
+            connection.submittedNamedStatements[this.name] = this.text;
+          }
         }
         try {
           connection.bind({
@@ -2500,6 +2518,8 @@ var require_query = __commonJS({
             valueMapper: utils.prepareValue
           });
         } catch (err) {
+          connection.close({ type: "S", name: this.name });
+          connection.sync();
           this.handleError(err, connection);
           return;
         }
@@ -2739,6 +2759,25 @@ var require_buffer_writer = __commonJS({
         this.offset += len;
         return this;
       }
+      // Write an Int32 byte-length prefix immediately followed by the string's UTF-8
+      // bytes. Postgres' Bind wire format prefixes every parameter with its length,
+      // and doing it in one method computes Buffer.byteLength ONCE — the previous
+      // `addInt32(Buffer.byteLength(s)).addString(s)` pairing scanned the string
+      // three times (byteLength for the prefix, byteLength again inside addString,
+      // then the encode), which is costly for large text parameters.
+      addInt32PrefixedString(string) {
+        const len = Buffer.byteLength(string);
+        this.ensure(4 + len);
+        const buffer = this.buffer;
+        let offset = this.offset;
+        buffer[offset++] = len >>> 24 & 255;
+        buffer[offset++] = len >>> 16 & 255;
+        buffer[offset++] = len >>> 8 & 255;
+        buffer[offset++] = len >>> 0 & 255;
+        buffer.write(string, offset, "utf-8");
+        this.offset = offset + len;
+        return this;
+      }
       add(otherBuffer) {
         this.ensure(otherBuffer.length);
         otherBuffer.copy(this.buffer, this.offset);
@@ -2760,6 +2799,10 @@ var require_buffer_writer = __commonJS({
         this.buffer = Buffer.allocUnsafe(this.size);
         return result;
       }
+      clear() {
+        this.offset = 5;
+        this.headerPosition = 0;
+      }
     };
     exports.Writer = Writer;
   }
@@ -2796,7 +2839,7 @@ var require_serializer = __commonJS({
       );
     };
     var sendSASLInitialResponseMessage = function(mechanism, initialResponse) {
-      writer.addCString(mechanism).addInt32(Buffer.byteLength(initialResponse)).addString(initialResponse);
+      writer.addCString(mechanism).addInt32PrefixedString(initialResponse);
       return writer.flush(
         112
         /* code.startup */
@@ -2855,8 +2898,7 @@ var require_serializer = __commonJS({
             0
             /* ParamType.STRING */
           );
-          paramWriter.addInt32(Buffer.byteLength(mappedVal));
-          paramWriter.addString(mappedVal);
+          paramWriter.addInt32PrefixedString(mappedVal);
         }
       }
     };
@@ -2868,7 +2910,13 @@ var require_serializer = __commonJS({
       const len = values.length;
       writer.addCString(portal).addCString(statement);
       writer.addInt16(len);
-      writeValues(values, config.valueMapper);
+      try {
+        writeValues(values, config.valueMapper);
+      } catch (err) {
+        writer.clear();
+        paramWriter.clear();
+        throw err;
+      }
       writer.addInt16(len);
       writer.add(paramWriter.flush());
       writer.addInt16(1);
@@ -3026,7 +3074,7 @@ var require_buffer_reader = __commonJS({
       cstring() {
         const start = this.offset;
         let end = start;
-        while (this.buffer[end++] !== 0) {
+        while (this.buffer[end++]) {
         }
         this.offset = end;
         return this.buffer.toString(this.encoding, start, end - 1);
@@ -3248,7 +3296,7 @@ var require_parser = __commonJS({
       const parameterCount = reader.int16();
       const message = new messages_1.ParameterDescriptionMessage(LATEINIT_LENGTH, parameterCount);
       for (let i = 0; i < parameterCount; i++) {
-        message.dataTypeIDs[i] = reader.int32();
+        message.dataTypeIDs[i] = reader.uint32();
       }
       return message;
     };
@@ -3353,7 +3401,8 @@ var require_dist = __commonJS({
   "node_modules/pg-protocol/dist/index.js"(exports) {
     "use strict";
     Object.defineProperty(exports, "__esModule", { value: true });
-    exports.DatabaseError = exports.serialize = exports.parse = void 0;
+    exports.DatabaseError = exports.serialize = void 0;
+    exports.parse = parse;
     var messages_1 = require_messages();
     Object.defineProperty(exports, "DatabaseError", { enumerable: true, get: function() {
       return messages_1.DatabaseError;
@@ -3368,7 +3417,6 @@ var require_dist = __commonJS({
       stream.on("data", (buffer) => parser.parse(buffer, callback));
       return new Promise((resolve) => stream.on("end", () => resolve()));
     }
-    exports.parse = parse;
   }
 });
 
@@ -3453,7 +3501,8 @@ var require_connection = __commonJS({
     "use strict";
     var EventEmitter = __require("events").EventEmitter;
     var { parse, serialize } = require_dist();
-    var { getStream, getSecureStream } = require_stream();
+    var stream = require_stream();
+    var { getStream } = stream;
     var flushBuffer = serialize.flush();
     var syncBuffer = serialize.sync();
     var endBuffer = serialize.end();
@@ -3468,7 +3517,9 @@ var require_connection = __commonJS({
         this._keepAlive = config.keepAlive;
         this._keepAliveInitialDelayMillis = config.keepAliveInitialDelayMillis;
         this.parsedStatements = {};
+        this.submittedNamedStatements = {};
         this.ssl = config.ssl || false;
+        this.sslNegotiation = config.sslNegotiation || "postgres";
         this._ending = false;
         this._emitMessage = false;
         const self = this;
@@ -3502,6 +3553,11 @@ var require_connection = __commonJS({
         if (!this.ssl) {
           return this.attachListeners(this.stream);
         }
+        if (this.sslNegotiation === "direct") {
+          return this.stream.once("connect", function() {
+            self.upgradeToSSL(host, reportStreamError);
+          });
+        }
         this.stream.once("data", function(buffer) {
           const responseCode = buffer.toString("utf8");
           switch (responseCode) {
@@ -3514,31 +3570,38 @@ var require_connection = __commonJS({
               self.stream.end();
               return self.emit("error", new Error("There was an error establishing an SSL connection"));
           }
-          const options = {
-            socket: self.stream
-          };
-          if (self.ssl !== true) {
-            Object.assign(options, self.ssl);
-            if ("key" in self.ssl) {
-              options.key = self.ssl.key;
-            }
-          }
-          const net = __require("net");
-          if (net.isIP && net.isIP(host) === 0) {
-            options.servername = host;
-          }
-          try {
-            self.stream = getSecureStream(options);
-          } catch (err) {
-            return self.emit("error", err);
-          }
-          self.attachListeners(self.stream);
-          self.stream.on("error", reportStreamError);
-          self.emit("sslconnect");
+          self.upgradeToSSL(host, reportStreamError);
         });
       }
-      attachListeners(stream) {
-        parse(stream, (msg) => {
+      upgradeToSSL(host, reportStreamError) {
+        const self = this;
+        const options = {
+          socket: self.stream
+        };
+        if (self.ssl !== true) {
+          Object.assign(options, self.ssl);
+          if ("key" in self.ssl) {
+            options.key = self.ssl.key;
+          }
+        }
+        if (self.sslNegotiation === "direct") {
+          options.ALPNProtocols = ["postgresql"];
+        }
+        const net = __require("net");
+        if (net.isIP && net.isIP(host) === 0) {
+          options.servername = host;
+        }
+        try {
+          self.stream = stream.getSecureStream(options);
+        } catch (err) {
+          return self.emit("error", err);
+        }
+        self.attachListeners(self.stream);
+        self.stream.on("error", reportStreamError);
+        self.emit("sslconnect");
+      }
+      attachListeners(stream2) {
+        parse(stream2, (msg) => {
           const eventName = msg.name === "error" ? "errorMessage" : msg.name;
           if (this._emitMessage) {
             this.emit("message", msg);
@@ -3966,8 +4029,8 @@ var require_client = __commonJS({
         return Number.isFinite(value) ? value : defaultValue;
       }
       if (typeof value === "string" && value.trim() !== "") {
-        const n = Number(value);
-        return Number.isFinite(n) ? n : defaultValue;
+        const n2 = Number(value);
+        return Number.isFinite(n2) ? n2 : defaultValue;
       }
       return defaultValue;
     }
@@ -4005,15 +4068,19 @@ var require_client = __commonJS({
         this.connection = c.connection || new Connection2({
           stream: c.stream,
           ssl: this.connectionParameters.ssl,
+          sslNegotiation: this.connectionParameters.sslnegotiation,
           keepAlive: c.keepAlive || false,
           keepAliveInitialDelayMillis: c.keepAliveInitialDelayMillis || 0,
           encoding: this.connectionParameters.client_encoding || "utf8"
         });
         this._queryQueue = [];
+        this._sentQueryQueue = [];
+        this.pipeline = Boolean(c.pipeline);
         this.binary = c.binary || defaults2.binary;
         this.processID = null;
         this.secretKey = null;
         this.ssl = this.connectionParameters.ssl || false;
+        this.sslNegotiation = this.connectionParameters.sslnegotiation || "postgres";
         if (this.ssl && this.ssl.key) {
           Object.defineProperty(this.ssl, "key", {
             enumerable: false
@@ -4043,6 +4110,8 @@ var require_client = __commonJS({
           enqueueError(activeQuery);
           this._activeQuery = null;
         }
+        this._sentQueryQueue.forEach(enqueueError);
+        this._sentQueryQueue.length = 0;
         this._queryQueue.forEach(enqueueError);
         this._queryQueue.length = 0;
       }
@@ -4074,7 +4143,9 @@ var require_client = __commonJS({
         }
         con.on("connect", function() {
           if (self.ssl) {
-            con.requestSsl();
+            if (self.sslNegotiation !== "direct") {
+              con.requestSsl();
+            }
           } else {
             con.startup(self.getStartupConf());
           }
@@ -4283,6 +4354,9 @@ var require_client = __commonJS({
           return;
         }
         this._activeQuery = null;
+        if (activeQuery.name) {
+          delete this.connection.submittedNamedStatements[activeQuery.name];
+        }
         activeQuery.handleError(msg, this.connection);
       }
       _handleRowDescription(msg) {
@@ -4339,6 +4413,7 @@ var require_client = __commonJS({
         }
         if (activeQuery.name) {
           this.connection.parsedStatements[activeQuery.name] = activeQuery.text;
+          delete this.connection.submittedNamedStatements[activeQuery.name];
         }
       }
       _handleCopyInResponse(msg) {
@@ -4405,6 +4480,9 @@ var require_client = __commonJS({
           });
         } else if (client._queryQueue.indexOf(query) !== -1) {
           client._queryQueue.splice(client._queryQueue.indexOf(query), 1);
+        } else if (client._sentQueryQueue.indexOf(query) !== -1) {
+          query.callback = () => {
+          };
         }
       }
       setTypeParser(oid, format, parseFn) {
@@ -4416,13 +4494,17 @@ var require_client = __commonJS({
       // escapeIdentifier and escapeLiteral moved to utility functions & exported
       // on PG
       // re-exported here for backwards compatibility
-      escapeIdentifier(str) {
-        return utils.escapeIdentifier(str);
+      escapeIdentifier(str2) {
+        return utils.escapeIdentifier(str2);
       }
-      escapeLiteral(str) {
-        return utils.escapeLiteral(str);
+      escapeLiteral(str2) {
+        return utils.escapeLiteral(str2);
       }
       _pulseQueryQueue() {
+        if (this.pipeline) {
+          this._pulsePipelinedQueryQueue();
+          return;
+        }
         if (this.readyForQuery === true) {
           this._activeQuery = this._queryQueue.shift();
           const activeQuery = this._getActiveQuery();
@@ -4443,6 +4525,30 @@ var require_client = __commonJS({
           }
         }
       }
+      _pulsePipelinedQueryQueue() {
+        if (!this._connected || !this._queryable) {
+          return;
+        }
+        while (this._queryQueue.length > 0) {
+          const query = this._queryQueue.shift();
+          this.hasExecuted = true;
+          const queryError = query.submit(this.connection);
+          if (queryError) {
+            process.nextTick(() => {
+              query.handleError(queryError, this.connection);
+            });
+            continue;
+          }
+          this._sentQueryQueue.push(query);
+        }
+        if (this.readyForQuery && !this._activeQuery && this._sentQueryQueue.length > 0) {
+          this._activeQuery = this._sentQueryQueue.shift();
+          this.readyForQuery = false;
+        }
+        if (!this._activeQuery && this._sentQueryQueue.length === 0 && this._queryQueue.length === 0 && this.hasExecuted) {
+          this.emit("drain");
+        }
+      }
       query(config, values, callback) {
         let query;
         let result;
@@ -4486,6 +4592,9 @@ var require_client = __commonJS({
             const index = this._queryQueue.indexOf(query);
             if (index > -1) {
               this._queryQueue.splice(index, 1);
+            } else if (this.pipeline) {
+              this.connection.stream.destroy();
+              return;
             }
             this._pulseQueryQueue();
           }, readTimeout);
@@ -4512,7 +4621,7 @@ var require_client = __commonJS({
           });
           return result;
         }
-        if (this._queryQueue.length > 0) {
+        if (this._queryQueue.length > 0 && !this.pipeline) {
           queryQueueLengthDeprecationNotice();
         }
         this._queryQueue.push(query);
@@ -4538,7 +4647,11 @@ var require_client = __commonJS({
             return this._Promise.resolve();
           }
         }
-        if (this._getActiveQuery() || !this._queryable) {
+        if (!this._queryable) {
+          this.connection.stream.destroy();
+        } else if (this.pipeline && (this._getActiveQuery() || this._sentQueryQueue.length > 0 || this._queryQueue.length > 0)) {
+          this.once("drain", () => this.connection.end());
+        } else if (this._getActiveQuery()) {
           this.connection.stream.destroy();
         } else {
           this.connection.end();
@@ -5028,7 +5141,7 @@ var require_query2 = __commonJS({
       sourceFunction: "routine"
     };
     NativeQuery.prototype.handleError = function(err) {
-      const fields = this.native.pq.resultErrorFields();
+      const fields = this.native && this.native.pq.resultErrorFields();
       if (fields) {
         for (const key in fields) {
           const normalizedFieldName = errorFieldMap[key] || key;
@@ -5161,6 +5274,8 @@ var require_client2 = __commonJS({
       this._connecting = false;
       this._connected = false;
       this._queryable = true;
+      this.pipeline = Boolean(config.pipeline);
+      this._pipelineInFlight = false;
       const cp = this.connectionParameters = new ConnectionParameters(config);
       if (config.nativeConnectionString) cp.nativeConnectionString = config.nativeConnectionString;
       this.user = cp.user;
@@ -5304,7 +5419,7 @@ var require_client2 = __commonJS({
         });
         return result;
       }
-      if (this._queryQueue.length > 0) {
+      if (this._queryQueue.length > 0 && !this.pipeline) {
         queryQueueLengthDeprecationNotice();
       }
       this._queryQueue.push(query);
@@ -5326,14 +5441,21 @@ var require_client2 = __commonJS({
           cb = (err) => err ? reject(err) : resolve();
         });
       }
-      this.native.end(function() {
-        self._connected = false;
-        self._errorAllQueries(new Error("Connection terminated"));
-        process.nextTick(() => {
-          self.emit("end");
-          if (cb) cb();
+      const doEnd = function() {
+        self.native.end(function() {
+          self._connected = false;
+          self._errorAllQueries(new Error("Connection terminated"));
+          process.nextTick(() => {
+            self.emit("end");
+            if (cb) cb();
+          });
         });
-      });
+      };
+      if (this.pipeline && (this._pipelineInFlight || this._queryQueue.length > 0)) {
+        this.once("drain", doEnd);
+      } else {
+        doEnd();
+      }
       return result;
     };
     Client2.prototype._hasActiveQuery = function() {
@@ -5343,6 +5465,9 @@ var require_client2 = __commonJS({
       if (!this._connected) {
         return;
       }
+      if (this.pipeline && !initialConnection) {
+        return this._pulsePipelinedQueryQueue();
+      }
       if (this._hasActiveQuery()) {
         return;
       }
@@ -5360,6 +5485,69 @@ var require_client2 = __commonJS({
         self._pulseQueryQueue();
       });
     };
+    Client2.prototype._pulsePipelinedQueryQueue = function() {
+      if (!this._connected || this._pipelineInFlight) {
+        return;
+      }
+      if (this._queryQueue.length === 0) {
+        if (this.hasExecuted) {
+          this.emit("drain");
+        }
+        return;
+      }
+      this._pipelineInFlight = true;
+      const self = this;
+      const queries = [];
+      const nativeQueries = [];
+      const utils = require_utils();
+      while (this._queryQueue.length > 0) {
+        const query = this._queryQueue.shift();
+        this.hasExecuted = true;
+        nativeQueries.push(query);
+        const values = query.values ? query.values.map(utils.prepareValue) : null;
+        const pipelineEntry = { text: query.text, name: query.name };
+        if (values) {
+          pipelineEntry.values = values;
+        }
+        if (query.name && this.namedQueries[query.name]) {
+          pipelineEntry._alreadyPrepared = true;
+        }
+        queries.push(pipelineEntry);
+      }
+      this.native.pipeline(queries, function(err, results) {
+        self._pipelineInFlight = false;
+        if (err) {
+          for (let i = 0; i < nativeQueries.length; i++) {
+            const q = nativeQueries[i];
+            q.native = self.native;
+            q.handleError(err);
+          }
+          self._pulsePipelinedQueryQueue();
+          return;
+        }
+        for (let i = 0; i < nativeQueries.length; i++) {
+          const q = nativeQueries[i];
+          const r = results[i];
+          q.native = self.native;
+          if (r.err) {
+            q.handleError(r.err);
+          } else {
+            if (q.name) {
+              self.namedQueries[q.name] = q.text;
+            }
+            q.state = "end";
+            q.emit("end", r.result);
+            if (q.callback) {
+              q.callback(null, r.result);
+            }
+          }
+          setImmediate(function() {
+            q.emit("_done");
+          });
+        }
+        self._pulsePipelinedQueryQueue();
+      });
+    };
     Client2.prototype.cancel = function(query) {
       if (this._activeQuery === query) {
         this.native.cancel(function() {
@@ -5707,6 +5895,11 @@ function loadEnv() {
   }
   return { ...cachedFileVars, ...process.env };
 }
+function estimateCostUsd(model, tokens) {
+  const [base = model, tier] = model.split(":");
+  const p = MODEL_PRICES[base] ?? MODEL_PRICES[MODEL_TIERS.standard];
+  return (tier === "flex" ? 0.5 : 1) * (tokens.input * p.input + tokens.cachedInput * p.cachedInput + tokens.output * p.output) / 1e6;
+}
 function loadConfig(env = loadEnv()) {
   return new Config(env);
 }
@@ -5719,10 +5912,22 @@ function redactUrlPassword(url) {
     return url;
   }
 }
-var cachedFileVars, DEFAULT_TENANT_ID, SECRETS, CORPORATE_API_KEY_ENV, DEFAULT_DATABASE_URL, MissingSecretError, Config;
+var cachedFileVars, MODEL_TIERS, MODEL_PRICES, DEFAULT_TENANT_ID, SECRETS, CORPORATE_API_KEY_ENV, DEFAULT_DATABASE_URL, MissingSecretError, Config;
 var init_config = __esm({
   "packages/shared/src/config.ts"() {
     "use strict";
+    MODEL_TIERS = {
+      fast: "claude-haiku-4-5",
+      standard: "claude-sonnet-5",
+      premium: "claude-opus-5"
+    };
+    MODEL_PRICES = {
+      "claude-opus-5": { input: 5, cachedInput: 0.5, output: 25 },
+      // Launch pricing made permanent (official pricing page, checked 2026-08-18).
+      "claude-sonnet-5": { input: 2, cachedInput: 0.2, output: 10 },
+      "claude-haiku-4-5": { input: 1, cachedInput: 0.1, output: 5 },
+      "gpt-5.6-luna": { input: 0.2, cachedInput: 0.02, output: 1.2 }
+    };
     DEFAULT_TENANT_ID = "00000000-0000-0000-0000-000000000002";
     SECRETS = {
       anthropicApiKey: {
@@ -5828,13 +6033,6 @@ var init_config = __esm({
   }
 });
 
-// packages/shared/src/ratelimit.ts
-var init_ratelimit = __esm({
-  "packages/shared/src/ratelimit.ts"() {
-    "use strict";
-  }
-});
-
 // packages/shared/src/sanitize.ts
 var init_sanitize = __esm({
   "packages/shared/src/sanitize.ts"() {
@@ -5851,6 +6049,8 @@ function validateFlowDiagram(d) {
   if (!short(f.title, 120)) errs.push("title: missing or too long");
   if (f.summary !== void 0 && !short(f.summary, 300))
     errs.push("summary: empty or too long");
+  if (f.explanation !== void 0 && !short(f.explanation, 4e3))
+    errs.push("explanation: empty or too long");
   const lanes = Array.isArray(f.lanes) ? f.lanes : [];
   if (lanes.length < 2 || lanes.length > 6)
     errs.push("lanes: need 2-6 phase bands");
@@ -5863,22 +6063,31 @@ function validateFlowDiagram(d) {
     } else laneKeys.add(l.key);
   }
   const nodes = Array.isArray(f.nodes) ? f.nodes : [];
-  if (nodes.length < 3 || nodes.length > 14)
-    errs.push("nodes: need 3-14 nodes");
+  if (nodes.length < 3 || nodes.length > 18)
+    errs.push("nodes: need 3-18 nodes");
   const ids = /* @__PURE__ */ new Set();
-  for (const n of nodes) {
-    if (!short(n?.id, 40) || !short(n?.title, 60)) {
+  for (const n2 of nodes) {
+    if (!short(n2?.id, 40) || !short(n2?.title, 60)) {
       errs.push("nodes: each needs id and title");
       continue;
     }
-    if (ids.has(n.id)) errs.push(`nodes: duplicate id ${n.id}`);
-    ids.add(n.id);
-    if (!laneKeys.has(n.lane ?? "")) errs.push(`nodes: ${n.id} unknown lane`);
-    if (!NODE_KINDS.has(n.kind ?? "")) errs.push(`nodes: ${n.id} unknown kind`);
-    if (n.subtitle !== void 0 && !short(n.subtitle, 60))
-      errs.push(`nodes: ${n.id} oversized subtitle`);
-    if (n.evidence !== void 0 && !Array.isArray(n.evidence))
-      errs.push(`nodes: ${n.id} evidence must be a list`);
+    if (ids.has(n2.id)) errs.push(`nodes: duplicate id ${n2.id}`);
+    ids.add(n2.id);
+    if (!laneKeys.has(n2.lane ?? "")) errs.push(`nodes: ${n2.id} unknown lane`);
+    if (!NODE_KINDS.has(n2.kind ?? "")) errs.push(`nodes: ${n2.id} unknown kind`);
+    if (n2.subtitle !== void 0 && !short(n2.subtitle, 60))
+      errs.push(`nodes: ${n2.id} oversized subtitle`);
+    if (n2.evidence !== void 0 && !Array.isArray(n2.evidence))
+      errs.push(`nodes: ${n2.id} evidence must be a list`);
+    if (Array.isArray(n2.evidence)) {
+      if (n2.evidence.length > 12)
+        errs.push(`nodes: ${n2.id} too many evidence entries`);
+      for (const ev of n2.evidence)
+        if (!short(ev, 200) || /[-]/.test(ev))
+          errs.push(`nodes: ${n2.id} evidence entry is not a short string`);
+    }
+    if (n2.description !== void 0 && !short(n2.description, 600))
+      errs.push(`nodes: ${n2.id} description empty or too long`);
   }
   const edges = Array.isArray(f.edges) ? f.edges : [];
   if (edges.length < 2 || edges.length > 24)
@@ -5889,7 +6098,7 @@ function validateFlowDiagram(d) {
       continue;
     }
     if (e.from === e.to) errs.push("edges: self-loop");
-    if (e.label !== void 0 && !short(e.label, 40))
+    if (e.label !== void 0 && !short(e.label, 60))
       errs.push("edges: oversized label");
     if (e.kind !== void 0 && !EDGE_KINDS.has(e.kind))
       errs.push("edges: unknown kind");
@@ -5957,7 +6166,55 @@ var init_capture_events = __esm({
       tool_name: 200,
       reason: 200
     };
-    cut = (s, n) => s === void 0 ? void 0 : s.length > n ? s.slice(0, n) : s;
+    cut = (s, n2) => s === void 0 ? void 0 : s.length > n2 ? s.slice(0, n2) : s;
+  }
+});
+
+// packages/shared/src/emoji.ts
+function isEmoji(s) {
+  return ONE_EMOJI.test(s);
+}
+var ONE_EMOJI;
+var init_emoji = __esm({
+  "packages/shared/src/emoji.ts"() {
+    "use strict";
+    ONE_EMOJI = new RegExp("^\\p{RGI_Emoji}$", "v");
+  }
+});
+
+// packages/shared/src/password.ts
+var init_password = __esm({
+  "packages/shared/src/password.ts"() {
+    "use strict";
+  }
+});
+
+// packages/shared/src/totp.ts
+var init_totp = __esm({
+  "packages/shared/src/totp.ts"() {
+    "use strict";
+  }
+});
+
+// packages/shared/src/brand.ts
+var BRAND_MARK_PATH, BRAND_ICON_SVG;
+var init_brand = __esm({
+  "packages/shared/src/brand.ts"() {
+    "use strict";
+    BRAND_MARK_PATH = "M14.47 157.37 L191.23 245.75 A24.00 24.00 0 0 1 204.50 267.21 L204.50 519.96 A12.00 12.00 0 0 1 187.13 530.70 L9.95 442.11 A18.00 18.00 0 0 1 0.00 426.01 L0.00 166.31 A10.00 10.00 0 0 1 14.47 157.37 Z M17.89 102.06 L203.22 9.39 A42.00 42.00 0 0 1 240.78 9.39 L421.89 99.94 A40.00 40.00 0 0 1 444.00 135.72 L444.00 195.70 A28.00 28.00 0 0 1 428.52 220.74 L253.97 308.01 A10.00 10.00 0 0 1 239.50 299.07 L239.50 249.29 A30.00 30.00 0 0 0 222.92 222.46 L17.89 119.94 A10.00 10.00 0 0 1 17.89 102.06 Z M256.08 332.67 L382.11 269.66 A40.00 40.00 0 0 1 417.89 269.66 L467.39 294.41 A40.00 40.00 0 0 1 489.50 330.19 L489.50 425.70 A10.00 10.00 0 0 1 483.97 434.65 L256.87 548.20 A12.00 12.00 0 0 1 239.50 537.46 L239.50 359.51 A30.00 30.00 0 0 1 256.08 332.67 Z";
+    BRAND_ICON_SVG = '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 640 640"><rect width="640" height="640" rx="120" fill="#ffffff"/><g transform="translate(117.48,89.6) scale(0.82747)" fill="#1c1c1a"><path d="' + BRAND_MARK_PATH + '"/></g></svg>';
+  }
+});
+
+// packages/shared/src/summary-report.ts
+var CONTROL;
+var init_summary_report = __esm({
+  "packages/shared/src/summary-report.ts"() {
+    "use strict";
+    CONTROL = new RegExp(
+      "[\\u0000-\\u0008\\u000b\\u000c\\u000e-\\u001f\\u007f]",
+      "g"
+    );
   }
 });
 
@@ -5969,10 +6226,14 @@ var init_src = __esm({
     init_memory();
     init_confidence();
     init_config();
-    init_ratelimit();
     init_sanitize();
     init_flow();
     init_capture_events();
+    init_emoji();
+    init_password();
+    init_totp();
+    init_brand();
+    init_summary_report();
     PROSE_STYLE = "Never use em dashes (\u2014) or en dashes (\u2013) anywhere; use commas, colons, periods, or parentheses instead.";
   }
 });
@@ -5986,8 +6247,11 @@ function getPool() {
     }
     pool = new esm_default.Pool({
       connectionString: config.databaseUrl,
+      // Per process (BJ-137): many instances times the default would fill Postgres; each role
+      // sets its own in the compose file. PgBouncer in front is the cloud ticket's (BJ-140).
+      max: Number(process.env.DATABASE_POOL_MAX) || 10,
       // Session GUC set in the startup packet — race-free, applies before any query.
-      options: `-c app.tenant_id=${config.tenantId}`
+      options: `-c app.tenant_id=${config.tenantId} -c hnsw.iterative_scan=strict_order`
     });
     pool.on("error", () => {
     });
@@ -6538,12 +6802,12 @@ var init_repository = __esm({
        * first (five logs cover a week completely, where a newest-N slice of raw objects sees only
        * the last hours of a busy range).
        */
-      async dailyLogsInRange(startIso, endIso, limit = 50) {
+      async dailyLogsInRange(startIso, endIso, limit = 50, order = "desc") {
         return (await this.pool.query(
           `SELECT ${MO_COLUMNS}, ${EV_AGG} FROM memory_object
          WHERE brain_id = $1 AND type = 'daily_log'
            AND occurred_at >= $2::timestamptz AND occurred_at < $3::timestamptz
-         ORDER BY occurred_at DESC LIMIT $4`,
+         ORDER BY occurred_at ${order === "asc" ? "ASC" : "DESC"} LIMIT $4`,
           [this.brainId, startIso, endIso, limit]
         )).rows;
       }
@@ -6729,6 +6993,20 @@ var init_repository = __esm({
         return r.rows;
       }
       // --- Overview / summaries ---
+      /** Compact freshness inputs for the whole Brain, without loading bodies or N+1 queries. */
+      async memoryFreshnessRows() {
+        return (await this.pool.query(
+          `SELECT m.id, m.type, m.title, m.updated_at AS "updatedAt",
+              m.last_verified_at AS "lastVerifiedAt", m.status,
+              EXISTS (SELECT 1 FROM superseded_object s WHERE s.object_id = m.id) AS superseded,
+              EXISTS (SELECT 1 FROM evidence_link el
+                      JOIN raw_artifact ra ON ra.id = el.raw_artifact_id
+                      WHERE el.memory_object_id = m.id AND ra.last_seen_at > m.updated_at) AS "evidenceChanged"
+       FROM memory_object m WHERE m.brain_id = $1
+       ORDER BY m.updated_at DESC, m.id`,
+          [this.brainId]
+        )).rows;
+      }
       /** Memory-object counts for this Brain, grouped by type and confidence (dashboard overview). */
       async counts() {
         const rows = (await this.pool.query(
@@ -6777,7 +7055,8 @@ var init_repository = __esm({
         return (await this.pool.query(
           `SELECT * FROM summary WHERE brain_id = $1
            AND ($3 OR created_by IS NULL OR created_by = $2)
-         ORDER BY created_at DESC`,
+         ORDER BY period_start DESC NULLS LAST,
+                  COALESCE(period_end, period_start) DESC, created_at DESC`,
           [this.brainId, viewerId ?? null, viewerId === void 0]
         )).rows;
       }
@@ -6797,8 +7076,8 @@ var init_repository = __esm({
         if (!isConfidence(confidence))
           throw new Error(`invalid confidence: ${confidence}`);
         const r = await this.pool.query(
-          `INSERT INTO summary (brain_id, timescale, title, body, period_start, period_end, confidence, created_by)
-       VALUES ($1,$2,$3,$4,$5::date,$6::date,$7,$8) RETURNING *`,
+          `INSERT INTO summary (brain_id, timescale, title, body, period_start, period_end, confidence, created_by, chronicle, data_through)
+       VALUES ($1,$2,$3,$4,$5::date,$6::date,$7,$8,$9::jsonb,$10::date) RETURNING *`,
           [
             this.brainId,
             input.timescale,
@@ -6807,7 +7086,9 @@ var init_repository = __esm({
             input.periodStartIso ?? null,
             input.periodEndIso ?? null,
             confidence,
-            input.createdBy ?? null
+            input.createdBy ?? null,
+            input.chronicle ? JSON.stringify(input.chronicle) : null,
+            input.dataThroughIso ?? null
           ]
         );
         return r.rows[0];
@@ -6842,14 +7123,69 @@ var init_repository = __esm({
        */
       async updateSummary(id, patch) {
         const r = await this.pool.query(
-          `UPDATE summary SET title = $3, body = $4, confidence = $5
+          `UPDATE summary SET title = $3, body = $4, confidence = $5,
+              chronicle = COALESCE($6::jsonb, chronicle),
+              data_through = COALESCE($7::date, data_through)
        WHERE id = $1 AND brain_id = $2 RETURNING *`,
-          [id, this.brainId, patch.title, patch.body, patch.confidence]
+          [
+            id,
+            this.brainId,
+            patch.title,
+            patch.body,
+            patch.confidence,
+            patch.chronicle ? JSON.stringify(patch.chronicle) : null,
+            patch.dataThroughIso ?? null
+          ]
+        );
+        const row = r.rows[0];
+        if (!row) throw new Error("summary not found in this Brain");
+        return row;
+      }
+      /**
+       * Claim the report job for one floor (summaries review S01): returns true for exactly one
+       * caller per (summary, hash), so two web processes never write the same report twice. A
+       * claim older than ten minutes counts as abandoned (the process died mid-call) and may be
+       * taken again; `force` retakes a failed one on the reader's request.
+       */
+      async claimSummaryReport(id, hash, opts = {}) {
+        const r = await this.pool.query(
+          `UPDATE summary
+          SET report_status = 'pending', report_status_hash = $3,
+              report_status_at = now(), report_error = NULL
+        WHERE id = $1 AND brain_id = $2
+          AND report_hash IS DISTINCT FROM $3
+          AND (report_status_hash IS DISTINCT FROM $3
+               OR report_status IS NULL
+               OR report_status_at < now() - interval '10 minutes'
+               OR (report_status = 'failed' AND $4))`,
+          [id, this.brainId, hash, Boolean(opts.force)]
+        );
+        return (r.rowCount ?? 0) > 0;
+      }
+      /** Store the validated report for the floor it was written from; the job is done. */
+      async saveSummaryReport(id, report, hash) {
+        const r = await this.pool.query(
+          `UPDATE summary
+          SET report = $3::jsonb, report_hash = $4, report_at = now(),
+              report_status = NULL, report_status_hash = NULL,
+              report_status_at = NULL, report_error = NULL
+        WHERE id = $1 AND brain_id = $2 RETURNING *`,
+          [id, this.brainId, JSON.stringify(report), hash]
         );
         const row = r.rows[0];
         if (!row) throw new Error("summary not found in this Brain");
         return row;
       }
+      /** Record why the report for this floor could not be written; the page shows it. */
+      async failSummaryReport(id, hash, error) {
+        await this.pool.query(
+          `UPDATE summary
+          SET report_status = 'failed', report_status_hash = $3,
+              report_status_at = now(), report_error = $4
+        WHERE id = $1 AND brain_id = $2`,
+          [id, this.brainId, hash, error.slice(0, 200)]
+        );
+      }
       /** Store the synthesized prose layer with the floor hash it was built from. */
       async saveSummarySynthesis(id, text, hash) {
         const r = await this.pool.query(
@@ -6862,13 +7198,23 @@ var init_repository = __esm({
         return row;
       }
       // --- Keyword search (Postgres FTS) ---
-      /** Ranked full-text keyword search over title/why/body in this Brain. */
+      /**
+       * Ranked full-text search over title/why/body in this Brain where any query word counts
+       * (documents sharing more and rarer words rank first). websearch_to_tsquery required EVERY
+       * word, so a sentence-length question or ticket intent matched nothing: measured on 314 real
+       * chat questions, 15% got a keyword hit, with OR nearly all do. plainto_tsquery still stems
+       * and drops stop words; its AND becomes OR. Documents holding every word come first and are
+       * flagged, so fusion can keep trusting them as before.
+       */
       async searchKeyword(query, limit = 10) {
         const r = await this.pool.query(
-          `SELECT ${MO_COLUMNS}, ${EV_AGG}, ts_rank(tsv, websearch_to_tsquery('english', $1)) AS rank
-       FROM memory_object
-       WHERE brain_id = $2 AND tsv @@ websearch_to_tsquery('english', $1)
-       ORDER BY rank DESC
+          `SELECT ${MO_COLUMNS}, ${EV_AGG}, ts_rank(tsv, q.kq) AS rank,
+              tsv @@ q.all_kq AS all_words
+       FROM memory_object,
+            (SELECT plainto_tsquery('english', $1) AS all_kq,
+                    replace(plainto_tsquery('english', $1)::text, ' & ', ' | ')::tsquery AS kq) q
+       WHERE brain_id = $2 AND tsv @@ q.kq
+       ORDER BY all_words DESC, rank DESC
        LIMIT $3`,
           [query, this.brainId, limit]
         );
@@ -6958,8 +7304,10 @@ var init_repository = __esm({
        */
       async saveDocPage(input) {
         const r = await this.pool.query(
-          `INSERT INTO doc_page (brain_id, slug, version, kind, title, model, markdown, source_hash, deleted)
-       SELECT $1, $2, COALESCE(max(version), 0) + 1, $3, $4, $5, $6, $7, $8
+          `INSERT INTO doc_page (brain_id, slug, version, kind, title, model, markdown, source_hash, deleted, icon)
+       SELECT $1, $2, COALESCE(max(version), 0) + 1, $3, $4, $5, $6, $7, $8,
+         COALESCE((SELECT icon FROM doc_page WHERE brain_id = $1 AND slug = $2
+                   ORDER BY version DESC LIMIT 1), $9)
        FROM doc_page WHERE brain_id = $1 AND slug = $2
        RETURNING *`,
           [
@@ -6970,11 +7318,21 @@ var init_repository = __esm({
             JSON.stringify(input.model),
             input.markdown,
             input.sourceHash,
-            input.deleted ?? false
+            input.deleted ?? false,
+            input.icon ?? null
           ]
         );
         return r.rows[0];
       }
+      /** Set the icon on a page's current version; false when the page does not exist. */
+      async setDocIcon(slug, icon) {
+        const r = await this.pool.query(
+          `UPDATE doc_page SET icon = $3 WHERE brain_id = $1 AND slug = $2
+         AND version = (SELECT max(version) FROM doc_page WHERE brain_id = $1 AND slug = $2)`,
+          [this.brainId, slug, icon]
+        );
+        return (r.rowCount ?? 0) > 0;
+      }
       /** The current documentation: latest version per slug, tombstones excluded, entry first. */
       async latestDocPages() {
         return this.docPagesAsOf();
@@ -7037,35 +7395,48 @@ var init_repository = __esm({
        * ponytail: tsvector computed per query; add a stored generated column + GIN index when a
        * Brain's doc tree grows past a few hundred pages.
        */
-      async docSearch(query, limit = 8) {
+      /**
+       * Docs search over the stored pages as they stood at `at` (default: now), so the time
+       * lens keeps its point in time (docs review R06). A page whose title equals the query
+       * ranks first, then title prefixes and title mentions, then full-text rank: an exact
+       * page never hides behind pages that merely mention it (R12).
+       */
+      async docSearch(query, limit = 8, at) {
         const terms = query.trim().toLowerCase().split(/\s+/).map((t) => t.replace(/[^\p{L}\p{N}]/gu, "")).filter(Boolean).slice(0, 8);
         if (terms.length === 0) return [];
         const tsq = terms.map((t, i) => i === terms.length - 1 ? `${t}:*` : t).join(" & ");
+        const plain = query.trim().toLowerCase().replace(/\s+/g, " ");
         const r = await this.pool.query(
           `WITH latest AS (
          SELECT DISTINCT ON (slug) * FROM doc_page
-         WHERE brain_id = $1
+         WHERE brain_id = $1 AND generated_at <= COALESCE($4, now())
          ORDER BY slug, version DESC
        )
        SELECT slug, kind, title,
          ts_headline('english', c.prose, q,
            'StartSel=[[, StopSel=]], MaxWords=18, MinWords=8') AS snippet
        FROM latest, to_tsquery('english', $2) q,
-         -- Snippets read as prose: fenced code, inline backticks, link URLs, and markdown
-         -- punctuation stripped for display only; the search vector keeps the raw markdown
-         -- so code and config names stay findable.
+         -- Snippets read as prose: fenced code, inline backticks, link targets (web,
+         -- repo-relative, and the docs' own page: scheme), and markdown punctuation
+         -- stripped for display only; the search vector keeps the raw markdown so code
+         -- and config names stay findable. (Template literal: regex backslashes are
+         -- doubled, a single one silently vanishes and the pattern never matches.)
          LATERAL (SELECT regexp_replace(regexp_replace(regexp_replace(
              markdown, '\`\`\`[^\`]*\`\`\`', ' ', 'g'),
-             ']((https?|brainjar-doku)[^)]*)', ']', 'g'),
+             '\\]\\((https?:|brainjar-doku/|features/|page:)[^)]*\\)', ']', 'g'),
              '[\`#*_|]', '', 'g') AS prose) c
        WHERE NOT deleted
          AND (setweight(to_tsvector('english', title), 'A')
               || setweight(to_tsvector('english', markdown), 'B')) @@ q
-       ORDER BY ts_rank(
-         setweight(to_tsvector('english', title), 'A')
-           || setweight(to_tsvector('english', markdown), 'B'), q) DESC
+       ORDER BY
+         (lower(title) = $5) DESC,
+         (lower(title) LIKE $5 || '%') DESC,
+         (position($5 in lower(title)) > 0) DESC,
+         ts_rank(
+           setweight(to_tsvector('english', title), 'A')
+             || setweight(to_tsvector('english', markdown), 'B'), q) DESC
        LIMIT $3`,
-          [this.brainId, tsq, limit]
+          [this.brainId, tsq, limit, at ?? null, plain]
         );
         return r.rows;
       }
@@ -7239,13 +7610,45 @@ var init_repository = __esm({
   }
 });
 
+// packages/db/src/ratelimit.ts
+var init_ratelimit = __esm({
+  "packages/db/src/ratelimit.ts"() {
+    "use strict";
+    init_pool();
+  }
+});
+
+// packages/db/src/auth-event.ts
+var init_auth_event = __esm({
+  "packages/db/src/auth-event.ts"() {
+    "use strict";
+    init_pool();
+  }
+});
+
+// packages/db/src/email-token.ts
+var init_email_token = __esm({
+  "packages/db/src/email-token.ts"() {
+    "use strict";
+    init_pool();
+  }
+});
+
 // packages/db/src/auth.ts
-var DEFAULT_TTL_HOURS;
+var DEFAULT_TTL_HOURS, LOGIN_FAILURE_WINDOW_MS, SCRYPT, REAUTH_WINDOW_MS, AVATAR_MAX_BYTES;
 var init_auth = __esm({
   "packages/db/src/auth.ts"() {
     "use strict";
+    init_src();
     init_pool();
+    init_ratelimit();
+    init_auth_event();
+    init_email_token();
     DEFAULT_TTL_HOURS = 24 * 90;
+    LOGIN_FAILURE_WINDOW_MS = 15 * 6e4;
+    SCRYPT = { N: 16384, r: 8, p: 1, maxmem: 64 * 1024 * 1024 };
+    REAUTH_WINDOW_MS = 5 * 6e4;
+    AVATAR_MAX_BYTES = 256 * 1024;
   }
 });
 
@@ -7269,11 +7672,43 @@ var init_oauth = __esm({
   }
 });
 
+// packages/db/src/totp.ts
+var CHALLENGE_TTL_MS;
+var init_totp2 = __esm({
+  "packages/db/src/totp.ts"() {
+    "use strict";
+    init_src();
+    init_pool();
+    CHALLENGE_TTL_MS = 5 * 6e4;
+  }
+});
+
+// packages/db/src/passkey.ts
+var CHALLENGE_TTL_MS2;
+var init_passkey = __esm({
+  "packages/db/src/passkey.ts"() {
+    "use strict";
+    init_pool();
+    CHALLENGE_TTL_MS2 = 5 * 6e4;
+  }
+});
+
+// packages/db/src/identity.ts
+var STATE_TTL_MS;
+var init_identity = __esm({
+  "packages/db/src/identity.ts"() {
+    "use strict";
+    init_pool();
+    STATE_TTL_MS = 5 * 6e4;
+  }
+});
+
 // packages/db/src/team.ts
 var init_team = __esm({
   "packages/db/src/team.ts"() {
     "use strict";
     init_pool();
+    init_auth();
   }
 });
 
@@ -7333,14 +7768,42 @@ var init_settings = __esm({
     APP_SETTING_KEYS = [
       "capture_mode",
       // transcript privacy: full | distilled | off
-      "author",
-      // developer identity stamped on captured reasoning
-      "promotion_threshold",
-      // signal/noise gate (0..1)
       "rationale_model",
       // Anthropic model for rationale/consolidation
-      "public_url"
+      "public_url",
       // this server's address as clients reach it (wizard command, MCP config)
+      // Outgoing mail (BJ-103); the password is a secret and lives next to the provider keys.
+      "smtp_host",
+      "smtp_port",
+      "smtp_user",
+      "smtp_secure",
+      // "1" = TLS from the start (465), else STARTTLS (587)
+      "mail_from",
+      // Sign in with a provider (BJ-112); the client secrets are secrets, see below.
+      "google_client_id",
+      "github_client_id",
+      // The legal pages the signup checkbox links to (BJ-113).
+      "terms_url",
+      "privacy_url",
+      // Voice chat (voice handoff, 2026-09-21): an explicit "true" or "false"; absent means on.
+      "voice_enabled",
+      // The GPT-Live voice (voice picker, 2026-09-22): an id from VOICE_OPTIONS; absent = default.
+      "voice_name",
+      // AI cost cap (BJ-139), set on the Operator page; env overrides, defaults in ingest/allowance.
+      "ai_contingent",
+      // "on" | "off": monthly contingent per workspace (default on in SaaS)
+      "ai_free_monthly_usd",
+      // Free workspace, USD per month
+      "ai_team_seat_monthly_usd",
+      // Team, USD per seat and month (applies once licenses exist)
+      "ai_operator_exempt",
+      // "true" | "false": operator accounts are never capped
+      "ai_daily_budget_usd",
+      // the instance's emergency brake on the company key; empty = off
+      "ai_budget_released_day",
+      // YYYY-MM-DD the operator lifted today's brake
+      "ai_budget_alerted_day"
+      // YYYY-MM-DD the operator was told the brake tripped
     ];
     PROVIDER_KEY_SETTINGS = {
       anthropic: "anthropic_api_key",
@@ -7373,11 +7836,112 @@ var init_tickets = __esm({
   }
 });
 
+// packages/db/src/jobs.ts
+var CAPTURE_JOB_KINDS, USER_JOB_KINDS;
+var init_jobs = __esm({
+  "packages/db/src/jobs.ts"() {
+    "use strict";
+    init_pool();
+    CAPTURE_JOB_KINDS = [
+      "capture-extract",
+      "capture-session",
+      "capture-transcript",
+      "capture-structure"
+    ];
+    USER_JOB_KINDS = [
+      ...CAPTURE_JOB_KINDS,
+      "deepscan",
+      "verify",
+      "summary-report",
+      "resynthesize"
+    ];
+  }
+});
+
+// packages/db/src/spend.ts
+function dayKey(at = /* @__PURE__ */ new Date()) {
+  return `day:${at.toISOString().slice(0, 10)}`;
+}
+async function addSpend(brainId, usd, at = /* @__PURE__ */ new Date(), pool2 = getPool()) {
+  if (!(usd > 0)) return;
+  await pool2.query(
+    `INSERT INTO llm_spend (key, usd)
+     SELECT k, $2 FROM (
+       SELECT $3::text AS k
+       UNION ALL
+       SELECT 'ws:' || b.owner_id || ':' || $4 FROM brain b
+       WHERE b.id = $1 AND b.owner_id IS NOT NULL
+     ) keys
+     ON CONFLICT (key) DO UPDATE SET usd = llm_spend.usd + EXCLUDED.usd, updated_at = now()`,
+    [brainId, usd, dayKey(at), at.toISOString().slice(0, 7)]
+  );
+}
+var init_spend = __esm({
+  "packages/db/src/spend.ts"() {
+    "use strict";
+    init_pool();
+  }
+});
+
+// packages/db/src/provider-rate.ts
+async function saveRate(keyId2, model, s, pool2 = getPool()) {
+  await pool2.query(
+    `INSERT INTO llm_rate (key_id, model, requests_limit, requests_remaining, requests_reset_at,
+       tokens_limit, tokens_remaining, tokens_reset_at, observed_at)
+     VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9)
+     ON CONFLICT (key_id, model) DO UPDATE SET
+       requests_limit = EXCLUDED.requests_limit,
+       requests_remaining = EXCLUDED.requests_remaining,
+       requests_reset_at = EXCLUDED.requests_reset_at,
+       tokens_limit = EXCLUDED.tokens_limit,
+       tokens_remaining = EXCLUDED.tokens_remaining,
+       tokens_reset_at = EXCLUDED.tokens_reset_at,
+       observed_at = EXCLUDED.observed_at
+     WHERE llm_rate.observed_at <= EXCLUDED.observed_at`,
+    [
+      keyId2,
+      model,
+      s.requestsLimit,
+      s.requestsRemaining,
+      s.requestsResetAt,
+      s.tokensLimit,
+      s.tokensRemaining,
+      s.tokensResetAt,
+      s.observedAt
+    ]
+  );
+}
+async function loadRate(keyId2, model, pool2 = getPool()) {
+  const r = await pool2.query(
+    "SELECT * FROM llm_rate WHERE key_id = $1 AND model = $2",
+    [keyId2, model]
+  );
+  const x = r.rows[0];
+  if (!x) return null;
+  const n2 = (v) => v === null ? null : Number(v);
+  return {
+    requestsLimit: n2(x.requests_limit),
+    requestsRemaining: n2(x.requests_remaining),
+    requestsResetAt: x.requests_reset_at,
+    tokensLimit: n2(x.tokens_limit),
+    tokensRemaining: n2(x.tokens_remaining),
+    tokensResetAt: x.tokens_reset_at,
+    observedAt: x.observed_at
+  };
+}
+var init_provider_rate = __esm({
+  "packages/db/src/provider-rate.ts"() {
+    "use strict";
+    init_pool();
+  }
+});
+
 // packages/db/src/ruleset.ts
 var init_ruleset = __esm({
   "packages/db/src/ruleset.ts"() {
     "use strict";
     init_pool();
+    init_tickets();
   }
 });
 
@@ -7396,11 +7960,21 @@ async function recordLlmUsage(u) {
       Math.max(0, Math.round(u.outputTokens))
     ]
   );
+  await addSpend(
+    u.brainId ?? null,
+    estimateCostUsd(u.model, {
+      input: u.inputTokens,
+      cachedInput: u.cachedInputTokens,
+      output: u.outputTokens
+    })
+  );
 }
 var init_usage = __esm({
   "packages/db/src/usage.ts"() {
     "use strict";
+    init_src();
     init_pool();
+    init_spend();
   }
 });
 
@@ -7414,12 +7988,21 @@ var init_src2 = __esm({
     init_auth();
     init_api_token();
     init_oauth();
+    init_ratelimit();
+    init_auth_event();
+    init_email_token();
+    init_totp2();
+    init_passkey();
+    init_identity();
     init_team();
     init_rbac();
     init_settings();
     init_notifications();
     init_conversations();
     init_tickets();
+    init_jobs();
+    init_spend();
+    init_provider_rate();
     init_ruleset();
     init_usage();
     init_audit_origin();
@@ -7671,14 +8254,14 @@ var init_values = __esm({
     };
     isArray = (val) => (isArray = Array.isArray, isArray(val));
     isReadonlyArray = isArray;
-    validatePositiveInteger = (name, n) => {
-      if (typeof n !== "number" || !Number.isInteger(n)) {
+    validatePositiveInteger = (name, n2) => {
+      if (typeof n2 !== "number" || !Number.isInteger(n2)) {
         throw new AnthropicError(`${name} must be an integer`);
       }
-      if (n < 0) {
+      if (n2 < 0) {
         throw new AnthropicError(`${name} must be a positive integer`);
       }
-      return n;
+      return n2;
     };
     safeJSON = (text) => {
       try {
@@ -7950,9 +8533,9 @@ function concatBytes(buffers) {
   }
   return output;
 }
-function encodeUTF8(str) {
+function encodeUTF8(str2) {
   let encoder;
-  return (encodeUTF8_ ?? (encoder = new globalThis.TextEncoder(), encodeUTF8_ = encoder.encode.bind(encoder)))(str);
+  return (encodeUTF8_ ?? (encoder = new globalThis.TextEncoder(), encodeUTF8_ = encoder.encode.bind(encoder)))(str2);
 }
 function decodeUTF8(bytes) {
   let decoder;
@@ -8171,12 +8754,12 @@ async function* iterSSEChunks(iterator) {
     yield data;
   }
 }
-function partition(str, delimiter) {
-  const index = str.indexOf(delimiter);
+function partition(str2, delimiter) {
+  const index = str2.indexOf(delimiter);
   if (index !== -1) {
-    return [str.substring(0, index), delimiter, str.substring(index + delimiter.length)];
+    return [str2.substring(0, index), delimiter, str2.substring(index + delimiter.length)];
   }
-  return [str, "", ""];
+  return [str2, "", ""];
 }
 var _Stream_client, Stream, SSEDecoder;
 var init_streaming = __esm({
@@ -8891,8 +9474,8 @@ var init_headers = __esm({
 });
 
 // node_modules/@anthropic-ai/sdk/internal/utils/path.mjs
-function encodeURIPath(str) {
-  return str.replace(/[^A-Za-z0-9\-._~!$&'()*+,;=:@]+/g, encodeURIComponent);
+function encodeURIPath(str2) {
+  return str2.replace(/[^A-Za-z0-9\-._~!$&'()*+,;=:@]+/g, encodeURIComponent);
 }
 var EMPTY, createPathTagFunction, path3;
 var init_path = __esm({
@@ -12288,11 +12871,118 @@ var init_sdk = __esm({
   }
 });
 
+// packages/ingest/src/provider-rate.ts
+import { createHash as createHash2 } from "node:crypto";
+function parseDuration(s) {
+  if (!s) return null;
+  let ms = 0;
+  let hit = false;
+  for (const [, n2, unit] of s.matchAll(/(\d+(?:\.\d+)?)(ms|h|m|s)/g)) {
+    hit = true;
+    ms += Number(n2) * UNIT_MS[unit];
+  }
+  return hit ? ms : null;
+}
+function parseRateHeaders(h, now = /* @__PURE__ */ new Date()) {
+  const num = (a, b) => {
+    const v = h.get(a) ?? h.get(b);
+    const n2 = v === null ? NaN : Number(v);
+    return Number.isFinite(n2) ? n2 : null;
+  };
+  const at = (openai, anthropic) => {
+    const d = parseDuration(h.get(openai));
+    if (d !== null) return new Date(now.getTime() + d);
+    const t = Date.parse(h.get(anthropic) ?? "");
+    return Number.isFinite(t) ? new Date(t) : null;
+  };
+  const s = {
+    requestsLimit: num(
+      "x-ratelimit-limit-requests",
+      "anthropic-ratelimit-requests-limit"
+    ),
+    requestsRemaining: num(
+      "x-ratelimit-remaining-requests",
+      "anthropic-ratelimit-requests-remaining"
+    ),
+    requestsResetAt: at(
+      "x-ratelimit-reset-requests",
+      "anthropic-ratelimit-requests-reset"
+    ),
+    tokensLimit: num(
+      "x-ratelimit-limit-tokens",
+      "anthropic-ratelimit-tokens-limit"
+    ),
+    tokensRemaining: num(
+      "x-ratelimit-remaining-tokens",
+      "anthropic-ratelimit-tokens-remaining"
+    ),
+    tokensResetAt: at(
+      "x-ratelimit-reset-tokens",
+      "anthropic-ratelimit-tokens-reset"
+    ),
+    observedAt: now
+  };
+  return s.requestsLimit === null && s.tokensLimit === null ? null : s;
+}
+function roomWaitMs(s, now = /* @__PURE__ */ new Date(), reserve = RESERVE) {
+  const wait = (limit, remaining, resetAt) => {
+    if (!limit || remaining === null || !resetAt) return 0;
+    const need = reserve * limit;
+    if (remaining >= need || resetAt <= now) return 0;
+    const span = resetAt.getTime() - s.observedAt.getTime();
+    const okAt = s.observedAt.getTime() + span * (need - remaining) / (limit - remaining);
+    return Math.max(0, Math.ceil(okAt - now.getTime()));
+  };
+  return Math.max(
+    wait(s.requestsLimit, s.requestsRemaining, s.requestsResetAt),
+    wait(s.tokensLimit, s.tokensRemaining, s.tokensResetAt)
+  );
+}
+async function awaitRoom(id, model) {
+  for (; ; ) {
+    const s = await loadRate(id, model).catch(() => null);
+    const ms = s ? roomWaitMs(s) : 0;
+    if (ms <= 0) return;
+    await sleep2(Math.min(ms, MAX_NAP_MS) + Math.random() * 250);
+  }
+}
+function noteRate(id, model, headers) {
+  const s = headers ? parseRateHeaders(headers) : null;
+  if (s) void saveRate(id, model, s).catch(() => {
+  });
+}
+function rateFetch(apiKey, model, automatic) {
+  const id = keyId(apiKey);
+  return async (input, init2) => {
+    if (automatic) await awaitRoom(id, model);
+    const res = await fetch(input, init2);
+    noteRate(id, model, res.headers);
+    return res;
+  };
+}
+var RESERVE, MAX_NAP_MS, sleep2, isAutomatic, keyId, UNIT_MS;
+var init_provider_rate2 = __esm({
+  "packages/ingest/src/provider-rate.ts"() {
+    "use strict";
+    init_src2();
+    RESERVE = 0.2;
+    MAX_NAP_MS = 6e4;
+    sleep2 = (ms) => new Promise((r) => setTimeout(r, ms));
+    isAutomatic = (meta) => !meta?.actor && !meta?.waiting;
+    keyId = (apiKey) => createHash2("sha256").update(apiKey).digest("hex").slice(0, 16);
+    UNIT_MS = { ms: 1, s: 1e3, m: 6e4, h: 36e5 };
+  }
+});
+
 // packages/ingest/src/llm.ts
 function rationaleModelId(env = process.env) {
   return env.BRAINJAR_RATIONALE_MODEL?.trim() || "claude-opus-5";
 }
 function logUsage(meta, model, usage) {
+  if (!meta?.brainId)
+    console.warn(
+      `brainjar: AI call without a Brain (workload ${meta?.workload ?? "other"}); it counts only toward the daily budget`
+    );
   void recordLlmUsage({
     brainId: meta?.brainId ?? null,
     workload: meta?.workload ?? "other",
@@ -12318,6 +13008,7 @@ var init_llm = __esm({
     "use strict";
     init_sdk();
     init_src2();
+    init_provider_rate2();
     cachedSystem = (system) => [
       {
         type: "text",
@@ -12330,9 +13021,12 @@ var init_llm = __esm({
       model;
       meta;
       constructor(opts) {
-        this.client = new Anthropic({ apiKey: opts.apiKey });
         this.model = opts.model ?? rationaleModelId();
         this.meta = opts.meta;
+        this.client = new Anthropic({
+          apiKey: opts.apiKey,
+          fetch: rateFetch(opts.apiKey, this.model, isAutomatic(opts.meta))
+        });
       }
       async complete({
         system,
@@ -12379,17 +13073,29 @@ var init_llm = __esm({
 var init_openai = __esm({
   "packages/ingest/src/openai.ts"() {
     "use strict";
+    init_src();
     init_llm();
+    init_provider_rate2();
   }
 });
 
-// packages/ingest/src/routing.ts
-var init_routing = __esm({
-  "packages/ingest/src/routing.ts"() {
+// packages/ingest/src/allowance.ts
+var init_allowance = __esm({
+  "packages/ingest/src/allowance.ts"() {
     "use strict";
     init_src2();
     init_src();
-    init_llm();
+  }
+});
+
+// packages/ingest/src/routing.ts
+var init_routing = __esm({
+  "packages/ingest/src/routing.ts"() {
+    "use strict";
+    init_src2();
+    init_src();
+    init_allowance();
+    init_llm();
     init_openai();
   }
 });
@@ -13716,7 +14422,7 @@ ${line}
 `.split("\n");
         } else {
           const i = lines.findIndex(
-            (l, n) => n >= range[0] && n < range[1] && /^\s*url\s*=/.test(l)
+            (l, n2) => n2 >= range[0] && n2 < range[1] && /^\s*url\s*=/.test(l)
           );
           next = [...lines];
           if (i >= 0) next[i] = line;
@@ -13936,17 +14642,25 @@ var init_daily_log = __esm({
 });
 
 // packages/ingest/src/summaries.ts
-var SYNTH_SYSTEM;
+var REPORT_SYSTEM;
 var init_summaries = __esm({
   "packages/ingest/src/summaries.ts"() {
     "use strict";
     init_src2();
     init_src();
-    SYNTH_SYSTEM = [
-      "You turn an engineering chronology into the period summary a product manager shares.",
-      "Account for every distinct piece of work in the input: group related items, drop none.",
-      "Return only bullet lines, one per line, each starting with '- '. No headings, no preamble, no code fences.",
-      "Product language: describe user-facing behavior and benefit; no file paths, no function names, no migration numbers.",
+    init_routing();
+    init_allowance();
+    REPORT_SYSTEM = [
+      "You write the period report of a software project for the people who work on it: what changed, why it matters, what was decided, what is still open.",
+      "Input: the captured records inside the period, numbered, oldest first, each with its date, time, type and title. Record types: feature (behavior that was built or changed), decision (a recorded direction, NOT a delivery), failure (an approach that did not work), event (a commit or another recorded event), note (a note or follow-up).",
+      "Return ONLY a JSON object, no prose around it, no code fence, with this shape:",
+      '{"lead": string, "sections": [{"heading": string, "body": string, "sources": [number]}], "decisions": [{"title": string, "body": string, "sources": [number]}], "open": [{"title": string, "body": string, "sources": [number]}], "timeline": [{"date": "YYYY-MM-DD", "title": string, "body": string, "sources": [number]}]}',
+      "lead: at most three sentences, about sixty words, a reader understands in thirty seconds: the most important changes and what they mean for the people using the project.",
+      "sections: two to six themes that emerge from THESE records (never a fixed list of topics); each body is one to three short paragraphs of plain product language; bullets only for genuinely parallel items; no headings inside a body; sources lists the record numbers the section rests on.",
+      "Say only what the records show. Delivered behavior needs feature or event records; a decision record means something was decided, not that it shipped, so describe it as decided. Never invent numbers, dates, names or sources.",
+      "decisions: only decisions that a decision record documents, cited by number; an empty array otherwise. open: only follow-ups the records name (failure or note records); when the records do not show whether it is resolved, say so; an empty array otherwise. timeline: only when at least three distinct milestones stand out on different days; each entry's date must be the date of a record it cites; an empty array otherwise.",
+      "Fit the length to the data: a short period with few records gets a short report. A month is read as a month: condense to its themes instead of listing weeks. A year is read as an arc: what changed between its start and its end.",
+      "No file paths, function names, migration numbers or shell commands. Write in English.",
       PROSE_STYLE
     ].join(" ");
   }
@@ -13972,11 +14686,11 @@ function slugify(title) {
 }
 function humans(names) {
   const count = /* @__PURE__ */ new Map();
-  for (const n of names) {
-    if (!n || n === "system") continue;
-    count.set(n, (count.get(n) ?? 0) + 1);
+  for (const n2 of names) {
+    if (!n2 || n2 === "system") continue;
+    count.set(n2, (count.get(n2) ?? 0) + 1);
   }
-  return [...count.entries()].sort((a, b) => b[1] - a[1]).map(([n]) => n);
+  return [...count.entries()].sort((a, b) => b[1] - a[1]).map(([n2]) => n2);
 }
 function moduleGroup(modulePath) {
   const segs = modulePath.split("/");
@@ -14027,7 +14741,8 @@ function buildDokuModel(input) {
       changes,
       decisions,
       locations,
-      evidenceUris
+      evidenceUris,
+      linkedDecisionIds
     }) => {
       let slug = slugify(feature.title);
       for (let i = 2; usedSlugs.has(slug) || RESERVED_SLUGS.has(slug); i++)
@@ -14066,13 +14781,16 @@ function buildDokuModel(input) {
         owner: explicitOwner ?? contributors[0] ?? null,
         contributors,
         narrative: null,
-        decisions: dedupeDecisions(decisions).map((d) => ({
-          title: d.title,
-          why: d.why,
-          by: d.created_by,
-          date: fmtDate(d.occurred_at),
-          objectId: d.id
-        })).sort((a, b) => a.date < b.date ? 1 : -1),
+        decisions: dedupeDecisions(decisions).map(
+          (d) => ({
+            title: d.title,
+            why: d.why,
+            by: d.created_by,
+            date: fmtDate(d.occurred_at),
+            objectId: d.id,
+            ...linkedDecisionIds ? { via: linkedDecisionIds.has(d.id) ? "link" : "location" } : {}
+          })
+        ).sort((a, b) => a.date < b.date ? 1 : -1),
         history,
         updated: history[0].date
       };
@@ -14147,8 +14865,19 @@ function renderEntryPage(model, base = "brainjar-doku/", narrative = null) {
   if (more.length) parts.push("## More", more.join("\n"));
   return parts.join("\n\n") + "\n";
 }
-function renderArchitecturePage(model) {
+function renderArchitecturePage(model, synthesized = {}) {
   const parts = [`# How it works`, DOKU_NOTICE];
+  if (synthesized.narrative) parts.push(synthesized.narrative);
+  for (const f of synthesized.flows ?? []) {
+    parts.push(
+      [
+        `## ${f.title}`,
+        ...f.summary ? [f.summary] : [],
+        ...f.explanation ? [f.explanation] : [],
+        flowLanesMarkdown(f)
+      ].join("\n\n")
+    );
+  }
   const idx = new Map(model.architecture.groups.map((g, i) => [g.name, i]));
   const lines = ["```mermaid", "flowchart LR"];
   for (const g of model.architecture.groups) {
@@ -14162,7 +14891,7 @@ function renderArchitecturePage(model) {
     );
   }
   lines.push("```");
-  parts.push(lines.join("\n"));
+  parts.push("## Module groups", lines.join("\n"));
   parts.push(
     "## Modules by group",
     model.architecture.groups.map(
@@ -14179,6 +14908,234 @@ function firstSentence(s) {
   const cut2 = t.slice(0, 200);
   return `${cut2.slice(0, cut2.lastIndexOf(" "))}\u2026`;
 }
+function parsePresentation(raw, ctx) {
+  const bad = (error) => ({ presentation: null, error, dropped: [] });
+  const o = raw;
+  if (!o || typeof o !== "object") return bad("not an object");
+  if (!str(o.summary, LIMIT.summary))
+    return bad("summary: missing or too long");
+  if (!Array.isArray(o.blocks) || o.blocks.length === 0)
+    return bad("blocks: need a non-empty list");
+  if (o.blocks.length > MAX_BLOCKS)
+    return bad(`blocks: more than ${MAX_BLOCKS}`);
+  const blocks = [];
+  const dropped = [];
+  const flowsPlaced = /* @__PURE__ */ new Set();
+  for (const [i, cand] of o.blocks.entries()) {
+    const b = cand;
+    const at = `block ${i + 1}`;
+    if (!b || typeof b !== "object") return bad(`${at}: not an object`);
+    const title = b.title;
+    switch (b.kind) {
+      case "text": {
+        if (title !== void 0 && !str(title, LIMIT.title))
+          return bad(`${at}: text title too long`);
+        if (!str(b.markdown, LIMIT.markdown))
+          return bad(`${at}: text markdown missing or too long`);
+        blocks.push({
+          kind: "text",
+          ...title ? { title: title.trim() } : {},
+          markdown: b.markdown.trim()
+        });
+        break;
+      }
+      case "steps": {
+        if (!str(title, LIMIT.title)) return bad(`${at}: steps need a title`);
+        const items = b.items;
+        if (!Array.isArray(items) || items.length === 0 || items.length > LIMIT.stepItems)
+          return bad(`${at}: steps need 1-${LIMIT.stepItems} items`);
+        const out = [];
+        for (const it of items) {
+          const s = it;
+          if (!str(s?.title, LIMIT.title) || !str(s?.body, LIMIT.stepBody, 0))
+            return bad(`${at}: step needs title and body`);
+          out.push({ title: s.title.trim(), body: s.body.trim() });
+        }
+        blocks.push({ kind: "steps", title: title.trim(), items: out });
+        break;
+      }
+      case "table": {
+        if (!str(title, LIMIT.title)) return bad(`${at}: table needs a title`);
+        const columns = b.columns;
+        if (!Array.isArray(columns) || columns.length < 2 || columns.length > LIMIT.columns || !columns.every((c) => str(c, 80)))
+          return bad(`${at}: table needs 2-${LIMIT.columns} column names`);
+        const rows = b.rows;
+        if (!Array.isArray(rows) || rows.length === 0 || rows.length > LIMIT.rows)
+          return bad(`${at}: table needs 1-${LIMIT.rows} rows`);
+        const outRows = [];
+        for (const r of rows) {
+          if (!Array.isArray(r) || r.length !== columns.length || !r.every((c) => typeof c === "string" && c.length <= LIMIT.cell))
+            return bad(
+              `${at}: every row needs exactly ${columns.length} cells`
+            );
+          outRows.push(r.map((c) => c.trim()));
+        }
+        blocks.push({
+          kind: "table",
+          title: title.trim(),
+          columns: columns.map((c) => c.trim()),
+          rows: outRows
+        });
+        break;
+      }
+      case "endpoint": {
+        const method = typeof b.method === "string" ? b.method.trim().toUpperCase() : "";
+        if (!HTTP_METHODS.has(method)) return bad(`${at}: unknown HTTP method`);
+        if (!str(b.path, LIMIT.endpointPath) || !/^\/\S*$/.test(b.path.trim()))
+          return bad(`${at}: endpoint path must start with /`);
+        if (!str(b.summary, LIMIT.endpointSummary))
+          return bad(`${at}: endpoint needs a summary`);
+        if (b.auth !== void 0 && !str(b.auth, LIMIT.auth))
+          return bad(`${at}: endpoint auth too long`);
+        const path20 = b.path.trim();
+        if (!ctx.factSheet.includes(path20)) {
+          dropped.push(`endpoint ${method} ${path20} (not in the fact sheet)`);
+          break;
+        }
+        blocks.push({
+          kind: "endpoint",
+          method,
+          path: path20,
+          summary: b.summary.trim(),
+          ...b.auth ? { auth: b.auth.trim() } : {}
+        });
+        break;
+      }
+      case "code": {
+        if (!str(title, LIMIT.title)) return bad(`${at}: code needs a title`);
+        if (typeof b.language !== "string" || !/^[a-z0-9+#.-]{1,20}$/i.test(b.language.trim()))
+          return bad(`${at}: code needs a language tag`);
+        if (!str(b.code, LIMIT.code))
+          return bad(`${at}: code missing or too long`);
+        blocks.push({
+          kind: "code",
+          title: title.trim(),
+          language: b.language.trim().toLowerCase(),
+          code: b.code.replace(/\s+$/, ""),
+          ...b.illustrative === true ? { illustrative: true } : {}
+        });
+        break;
+      }
+      case "callout": {
+        if (b.tone !== "note" && b.tone !== "warning")
+          return bad(`${at}: callout tone must be note or warning`);
+        if (!str(b.text, LIMIT.callout)) return bad(`${at}: callout text`);
+        blocks.push({ kind: "callout", tone: b.tone, text: b.text.trim() });
+        break;
+      }
+      case "flow": {
+        if (!str(title, LIMIT.title)) return bad(`${at}: flow needs a title`);
+        if (b.source !== "flowDiagram" && b.source !== "flow")
+          return bad(`${at}: flow source must be flowDiagram or flow`);
+        const exists2 = b.source === "flowDiagram" ? ctx.hasFlowDiagram : ctx.hasFlow;
+        if (!exists2 || flowsPlaced.has(b.source)) {
+          dropped.push(
+            `flow ${b.source} (${exists2 ? "placed twice" : "no such diagram"})`
+          );
+          break;
+        }
+        flowsPlaced.add(b.source);
+        blocks.push({ kind: "flow", title: title.trim(), source: b.source });
+        break;
+      }
+      default:
+        return bad(`${at}: unknown kind ${String(b.kind)}`);
+    }
+  }
+  if (blocks.length === 0) return bad("blocks: nothing left after validation");
+  return {
+    presentation: { version: 1, summary: o.summary.trim(), blocks },
+    error: null,
+    dropped
+  };
+}
+function flowLanesMarkdown(d) {
+  return d.lanes.map((l) => {
+    const nodes = d.nodes.filter((n2) => n2.lane === l.key).map((n2) => n2.title).join(", ");
+    return `- **${l.title}**: ${nodes || "(no stations)"}`;
+  }).join("\n");
+}
+function renderBlocksMarkdown(p, diagrams = {}) {
+  const parts = [];
+  for (const b of p.blocks) {
+    switch (b.kind) {
+      case "text":
+        parts.push([h2(b.title), b.markdown].filter(Boolean).join("\n\n"));
+        break;
+      case "steps":
+        parts.push(
+          [
+            h2(b.title),
+            b.items.map(
+              (s, i) => `${i + 1}. **${s.title}**${s.body ? ` ${s.body}` : ""}`
+            ).join("\n")
+          ].join("\n\n")
+        );
+        break;
+      case "table":
+        parts.push(
+          [
+            h2(b.title),
+            [
+              `| ${b.columns.map(mdCell).join(" | ")} |`,
+              `|${b.columns.map(() => "---").join("|")}|`,
+              ...b.rows.map((r) => `| ${r.map(mdCell).join(" | ")} |`)
+            ].join("\n")
+          ].join("\n\n")
+        );
+        break;
+      case "endpoint":
+        parts.push(
+          [
+            `### \`${b.method} ${b.path}\``,
+            b.summary,
+            ...b.auth ? [`Authentication: ${b.auth}`] : []
+          ].join("\n\n")
+        );
+        break;
+      case "code":
+        parts.push(
+          [
+            `**${b.title}**${b.illustrative ? " (illustrative example, replace the placeholders)" : ""}`,
+            `\`\`\`${b.language}
+${b.code}
+\`\`\``
+          ].join("\n\n")
+        );
+        break;
+      case "callout":
+        parts.push(
+          `> **${b.tone === "warning" ? "Warning" : "Note"}:** ${b.text.replace(/\n/g, "\n> ")}`
+        );
+        break;
+      case "flow": {
+        const lines = [h2(b.title)];
+        if (b.source === "flowDiagram" && diagrams.flowDiagram) {
+          const d = diagrams.flowDiagram;
+          lines.push(
+            `_Runtime flow diagram: ${d.title}. Interactive on the web page; its lanes and stations:_`
+          );
+          lines.push(flowLanesMarkdown(d));
+        } else if (b.source === "flow" && diagrams.flow) {
+          lines.push(
+            diagrams.flow.steps.map((s, i) => `${i + 1}. ${s}`).join("\n")
+          );
+        }
+        parts.push(lines.join("\n\n"));
+        break;
+      }
+    }
+  }
+  return parts.join("\n\n");
+}
+function pageBody(f) {
+  if (f.presentation)
+    return [
+      f.presentation.summary,
+      renderBlocksMarkdown(f.presentation, f)
+    ].join("\n\n");
+  return f.body ?? null;
+}
 function renderFeaturePage(f) {
   const meta = [
     "| | |",
@@ -14189,8 +15146,9 @@ function renderFeaturePage(f) {
     ...f.locations.length ? [`| Code | ${f.locations.map((l) => `\`${l}\``).join(", ")} |`] : []
   ];
   const parts = [`# ${f.docTitle ?? f.title}`, meta.join("\n")];
-  if (f.body) {
-    parts.push(f.body);
+  const body = pageBody(f);
+  if (body) {
+    parts.push(body);
   } else {
     if (f.narrative) parts.push(f.narrative);
     parts.push("## What it does", f.what);
@@ -14236,7 +15194,7 @@ function renderCategoryPage(model) {
 function renderChangelogPage(model) {
   const parts = [`# Changelog`, DOKU_NOTICE];
   for (const day of model.changelog) {
-    const counts = Object.entries(day.counts).map(([t, n]) => `${n} ${t}${n === 1 ? "" : "s"}`).join(" \xB7 ");
+    const counts = Object.entries(day.counts).map(([t, n2]) => `${n2} ${t}${n2 === 1 ? "" : "s"}`).join(" \xB7 ");
     const who = day.contributors.length ? ` \xB7 by ${day.contributors.join(", ")}` : "";
     parts.push(
       `## ${day.date}`,
@@ -14333,7 +15291,7 @@ function renderDokuPages(model) {
   }
   return pages;
 }
-var normTitle, DOC_SECTIONS, fmtDate, MAX_GROUPS, MAX_HIGHLIGHTS, HIGHLIGHT_TYPES, RESERVED_SLUGS, DOKU_NOTICE, mermaidId, mermaidLabel, mdCell, asRecord;
+var normTitle, DOC_SECTIONS, fmtDate, MAX_GROUPS, MAX_HIGHLIGHTS, HIGHLIGHT_TYPES, RESERVED_SLUGS, DOKU_NOTICE, mermaidId, mermaidLabel, mdCell, HTTP_METHODS, MAX_BLOCKS, LIMIT, str, h2, asRecord;
 var init_doku_model = __esm({
   "packages/ingest/src/doku-model.ts"() {
     "use strict";
@@ -14360,12 +15318,39 @@ var init_doku_model = __esm({
     mermaidId = (name, i) => `g${i}`;
     mermaidLabel = (s) => s.replace(/"/g, "'");
     mdCell = (s) => (s ?? "").replace(/\|/g, "\\|").replace(/\s+/g, " ").trim();
+    HTTP_METHODS = /* @__PURE__ */ new Set([
+      "GET",
+      "POST",
+      "PUT",
+      "PATCH",
+      "DELETE",
+      "HEAD",
+      "OPTIONS"
+    ]);
+    MAX_BLOCKS = 40;
+    LIMIT = {
+      title: 120,
+      summary: 300,
+      markdown: 2e4,
+      stepItems: 20,
+      stepBody: 1e3,
+      columns: 6,
+      rows: 40,
+      cell: 400,
+      endpointPath: 200,
+      endpointSummary: 400,
+      auth: 200,
+      code: 6e3,
+      callout: 600
+    };
+    str = (v, max, min = 1) => typeof v === "string" && v.trim().length >= min && v.length <= max;
+    h2 = (t) => t ? `## ${t.trim()}` : null;
     asRecord = (v) => v;
   }
 });
 
 // packages/ingest/src/doku.ts
-import { createHash as createHash2 } from "node:crypto";
+import { createHash as createHash3 } from "node:crypto";
 import { mkdir as mkdir10, readFile as readFile10, rm as rm6, stat, writeFile as writeFile10 } from "node:fs/promises";
 import path15 from "node:path";
 function bodyLocations(o) {
@@ -14397,10 +15382,10 @@ async function loadDokuData(brainId, root) {
         relations: ["changes", "affects", "mentions"]
       });
       const changes = neighbors.filter(
-        (n) => n.id !== feature.id && n.type === "event"
+        (n2) => n2.id !== feature.id && n2.type === "event"
       );
       const linkedDecisions = neighbors.filter(
-        (n) => n.id !== feature.id && n.type === "decision"
+        (n2) => n2.id !== feature.id && n2.type === "decision"
       );
       const linkedModules = neighbors.filter(isModule).map(moduleName);
       const locations = [
@@ -14419,7 +15404,14 @@ async function loadDokuData(brainId, root) {
         feature.id,
         ...changes.map((c) => c.id)
       ]);
-      return { feature, changes, decisions, locations, evidenceUris };
+      return {
+        feature,
+        changes,
+        decisions,
+        locations,
+        evidenceUris,
+        linkedDecisionIds: new Set(linkedDecisions.map((d) => d.id))
+      };
     })
   );
   const days = (await Promise.all(
@@ -14457,20 +15449,50 @@ async function loadDokuData(brainId, root) {
     scripts
   };
 }
-function parseDocPage(raw, categoryKeys) {
+function aiState(m) {
+  return {
+    factHash: typeof m?.factHash === "string" ? m.factHash : "",
+    aiIncomplete: m?.aiIncomplete === true,
+    aiAttempts: typeof m?.aiAttempts === "number" ? m.aiAttempts : 0
+  };
+}
+function aiComplete(kind, m) {
+  if (!m) return false;
+  const text = (v) => typeof v === "string" && v.trim().length > 0;
+  switch (kind) {
+    case "entry":
+    case "architecture":
+      return text(m.narrative);
+    case "feature":
+      return (Boolean(m.presentation) || text(m.body)) && text(m.category);
+    case "category":
+      return text(m.body);
+    default:
+      return true;
+  }
+}
+function parseDocPage(raw, categoryKeys, ctx) {
+  const bad = (error2) => ({ page: null, error: error2, dropped: [] });
   const match = raw.match(/\{[\s\S]*\}/);
-  if (!match) return null;
+  if (!match) return bad("no JSON");
+  let obj;
   try {
-    const obj = JSON.parse(match[0]);
-    const title = typeof obj.title === "string" ? obj.title.trim() : "";
-    const category = typeof obj.category === "string" ? obj.category.trim() : "";
-    const body = typeof obj.body === "string" ? obj.body.trim() : "";
-    if (!title || title.length > 120 || !body) return null;
-    if (!categoryKeys.includes(category)) return null;
-    return { title, category, body };
+    obj = JSON.parse(match[0]);
   } catch {
-    return null;
-  }
+    return bad("invalid JSON (truncated reply?)");
+  }
+  const title = typeof obj.title === "string" ? obj.title.trim() : "";
+  const category = typeof obj.category === "string" ? obj.category.trim() : "";
+  if (!title || title.length > 120) return bad("title: missing or too long");
+  if (!categoryKeys.includes(category)) return bad("category: unknown key");
+  const icon = typeof obj.icon === "string" && isEmoji(obj.icon.trim()) ? obj.icon.trim() : null;
+  const { presentation, error, dropped } = parsePresentation(obj, ctx);
+  if (!presentation) return bad(error ?? "presentation invalid");
+  return {
+    page: { title, category, presentation, icon },
+    error: null,
+    dropped
+  };
 }
 function parseTaxonomy(raw) {
   const match = raw.match(/\{[\s\S]*\}/);
@@ -14485,25 +15507,53 @@ function parseTaxonomy(raw) {
       const name = typeof r.name === "string" ? r.name.trim() : "";
       const description = typeof r.description === "string" ? r.description.trim() : "";
       if (!/^[a-z0-9-]{2,40}$/.test(key) || !name || !description) return null;
+      if (name.length > 80 || description.length > 240) return null;
       out.push({ key, name, description });
     }
-    if (out.length < 3 || out.length > 8) return null;
+    if (out.length < 1 || out.length > 40) return null;
     if (new Set(out.map((c) => c.key)).size !== out.length) return null;
     return out;
   } catch {
     return null;
   }
 }
+function parseRefile(raw, slugs, keys) {
+  let pages = null;
+  const match = raw.match(/\{[\s\S]*\}/);
+  if (match) {
+    try {
+      const obj = JSON.parse(match[0]);
+      if (typeof obj.pages === "object" && obj.pages !== null && !Array.isArray(obj.pages))
+        pages = obj.pages;
+    } catch {
+    }
+  }
+  if (!pages) {
+    pages = {};
+    for (const m of raw.matchAll(/"([^"\n]+)"\s*:\s*"([^"\n]*)"/g))
+      pages[m[1]] = m[2];
+  }
+  const known = new Set(keys);
+  const out = {};
+  for (const slug of slugs) {
+    const key = pages[slug];
+    if (typeof key === "string" && known.has(key.trim()))
+      out[slug] = key.trim();
+  }
+  return Object.keys(out).length ? out : null;
+}
 function parseCategoryBody(raw, memberSlugs) {
   let body = raw.trim();
-  if (!body || body.length > 9e3) return null;
+  if (!body || body.length > 2e4) return null;
   const known = new Set(memberSlugs);
   body = body.replace(
     /\[([^\]]+)\]\(page:([^)\s]+)\)/g,
     (whole, text, slug) => known.has(slug) ? whole : text
   );
-  const links = [...body.matchAll(/\(page:([^)\s]+)\)/g)].map((m) => m[1]);
-  if (links.length === 0 || links.some((s) => !known.has(s))) return null;
+  body = body.replace(
+    /\(page:([^)\s]+)\)/g,
+    (whole, slug) => known.has(slug) ? whole : ""
+  );
   return body;
 }
 function archNotesInput(model) {
@@ -14597,13 +15647,19 @@ function parseArchFlows(raw, knownModules) {
   const errors = [];
   for (const cand of obj.flows.slice(0, 4)) {
     const f = cand;
+    if (f && typeof f === "object") {
+      const x = f.explanation;
+      if (typeof x === "string" && x.trim() && x.length <= 4e3)
+        f.explanation = x.trim();
+      else delete f.explanation;
+    }
     if (Array.isArray(f?.nodes)) {
-      for (const n of f.nodes) {
-        if (Array.isArray(n?.evidence)) {
-          n.evidence = n.evidence.filter(
+      for (const n2 of f.nodes) {
+        if (Array.isArray(n2?.evidence)) {
+          n2.evidence = n2.evidence.filter(
             (p) => typeof p === "string" && knownModules.has(p)
           );
-          if (n.evidence.length === 0) delete n.evidence;
+          if (n2.evidence.length === 0) delete n2.evidence;
         }
       }
     }
@@ -14627,12 +15683,12 @@ function parseFeatureFlow(raw, slug, knownPaths) {
   const f = obj.flow;
   f.slug = `${slug.slice(0, 59)}-flow`;
   if (Array.isArray(f?.nodes)) {
-    for (const n of f.nodes) {
-      if (Array.isArray(n?.evidence)) {
-        n.evidence = n.evidence.filter(
+    for (const n2 of f.nodes) {
+      if (Array.isArray(n2?.evidence)) {
+        n2.evidence = n2.evidence.filter(
           (p) => typeof p === "string" && knownPaths.has(p)
         );
-        if (n.evidence.length === 0) delete n.evidence;
+        if (n2.evidence.length === 0) delete n2.evidence;
       }
     }
   }
@@ -14657,7 +15713,7 @@ function parseFlow(raw, configKeys) {
   const edges = obj.edges;
   if (!Array.isArray(edges) || edges.length === 0 || !edges.every(
     (e) => Array.isArray(e) && e.length === 2 && e.every(
-      (n) => Number.isInteger(n) && n >= 0 && n < steps.length
+      (n2) => Number.isInteger(n2) && n2 >= 0 && n2 < steps.length
     ) && e[0] !== e[1]
   ))
     return bad("edges: need valid [from,to] index pairs");
@@ -14705,9 +15761,16 @@ async function generateDokuInner(brainId, opts = {}) {
   const repo = brainRepo(brainId);
   const meta = new Map((await repo.docPageMeta()).map((m) => [m.slug, m]));
   const storedBySlug = /* @__PURE__ */ new Map();
+  const storedRows = /* @__PURE__ */ new Map();
   try {
-    for (const p of await repo.latestDocPages())
+    for (const p of await repo.latestDocPages()) {
       storedBySlug.set(p.slug, p.model);
+      storedRows.set(p.slug, {
+        title: p.title,
+        model: p.model,
+        markdown: p.markdown
+      });
+    }
   } catch {
   }
   const takenTitle = /* @__PURE__ */ new Map();
@@ -14726,10 +15789,11 @@ async function generateDokuInner(brainId, opts = {}) {
     const stored = storedBySlug.get("index")?.categories;
     if (Array.isArray(stored) && stored.length) categories = stored;
   }
+  const storedTaxonomy = JSON.stringify(categories);
   const hasNewFeature = pages.some(
     (p) => p.kind === "feature" && !meta.get(p.slug)
   );
-  if (opts.llm && (categories.length === 0 || hasNewFeature)) {
+  if (opts.llm && (categories.length === 0 || hasNewFeature || opts.retaxonomy)) {
     try {
       const next = parseTaxonomy(
         await opts.llm.complete({
@@ -14743,7 +15807,9 @@ async function generateDokuInner(brainId, opts = {}) {
               (f) => `- ${f.title}: ${firstSentence(f.what)}`
             )
           ].join("\n"),
-          maxTokens: 900
+          // Room for a large product's taxonomy; an invalid or clipped reply keeps the
+          // stored one (parseTaxonomy returns null).
+          maxTokens: 3e3
         })
       );
       if (next) categories = next;
@@ -14751,42 +15817,82 @@ async function generateDokuInner(brainId, opts = {}) {
     }
   }
   const categoryKeys = categories.map((c) => c.key);
+  const taxonomyChanged = JSON.stringify(categories) !== storedTaxonomy;
+  const endpointFacts = [];
+  for (const [slug, m] of storedBySlug) {
+    const p = m.presentation;
+    if (!Array.isArray(p?.blocks)) continue;
+    for (const b of p.blocks)
+      if (b.kind === "endpoint")
+        endpointFacts.push({
+          slug,
+          title: typeof m.docTitle === "string" ? m.docTitle : slug,
+          method: b.method,
+          path: b.path,
+          summary: b.summary,
+          ...b.auth ? { auth: b.auth } : {}
+        });
+  }
   let written = 0;
   let polished = false;
   const seen = /* @__PURE__ */ new Set();
   const featureInfo = [];
+  const save = async (input) => {
+    await repo.saveDocPage(input);
+    storedRows.set(input.slug, {
+      title: input.title,
+      model: input.model,
+      markdown: input.markdown
+    });
+    storedBySlug.set(input.slug, input.model);
+    written++;
+  };
   for (const page of pages) {
     seen.add(page.slug);
     const rawStructure = page.kind === "architecture" ? (() => {
       const raw = page.model.raw;
       return raw ? sha1(JSON.stringify([raw.modules, raw.edges])) : "";
     })() : "";
+    const factHash = sha1(page.markdown);
     const sourceHash = sha1(
-      page.markdown + (page.kind === "entry" ? "v3" : page.kind === "feature" ? (
-        // f6: flow slug fix + retry after the silent 0-of-44 run.
-        "f6"
+      page.markdown + (page.kind === "entry" ? "v4" : page.kind === "feature" ? (
+        // f7: the block presentation model (docs redesign) regenerates every
+        // feature page once; run with `only` first for a representative sample.
+        "f7"
       ) : page.kind === "architecture" ? (
-        // a5: more flows, tighter labels — existing brains regenerate the page once.
-        "a5" + rawStructure
+        // a6: flow explanations + full markdown (docs hubs) regenerate the page once.
+        "a6" + rawStructure
       ) : "")
     );
     const prev = meta.get(page.slug);
-    if (prev && !prev.deleted && prev.source_hash === sourceHash && !storedCollisions.has(page.slug)) {
+    const stored = storedBySlug.get(page.slug);
+    const state = aiState(stored);
+    const required = Boolean(opts.llm && page.polishable);
+    const outsideSample = Boolean(opts.only && !opts.only.includes(page.slug));
+    const unchanged = Boolean(
+      prev && !prev.deleted && prev.source_hash === sourceHash
+    );
+    const retry = required && unchanged && (state.aiIncomplete || !aiComplete(page.kind, stored)) && (state.aiAttempts < MAX_AI_ATTEMPTS || Boolean(opts.forceRetry));
+    const entryTaxonomy = page.kind === "entry" && taxonomyChanged;
+    if (prev && !prev.deleted && (outsideSample || unchanged && !storedCollisions.has(page.slug) && !retry && !entryTaxonomy)) {
       if (page.kind === "feature") {
-        const stored = storedBySlug.get(page.slug);
+        const s = stored;
         const f = page.model;
         featureInfo.push({
           slug: page.slug,
-          title: typeof stored?.docTitle === "string" ? stored.docTitle : page.title,
+          title: typeof s?.docTitle === "string" ? s.docTitle : page.title,
           what: f.what,
           updated: f.updated,
-          category: typeof stored?.category === "string" ? stored.category : null
+          category: typeof s?.category === "string" ? s.category : null
         });
       }
       continue;
     }
+    const sameFacts = stored !== void 0 && state.factHash === factHash;
     let markdown = page.markdown;
     let model = page.model;
+    let icon = null;
+    let ok2 = !required;
     if (opts.llm && page.polishable && page.kind === "architecture") {
       try {
         const { notes } = parseArchNotes(
@@ -14800,6 +15906,7 @@ async function generateDokuInner(brainId, opts = {}) {
         if (notes) {
           model = { ...model, narrative: notes.narrative, roles: notes.roles };
           polished = true;
+          ok2 = true;
         }
       } catch {
       }
@@ -14818,61 +15925,47 @@ async function generateDokuInner(brainId, opts = {}) {
         }
       } catch {
       }
+      if (!ok2 && sameFacts) {
+        const s = stored;
+        const kept = model;
+        model = {
+          ...model,
+          ...typeof s.narrative === "string" ? { narrative: s.narrative, roles: s.roles } : {},
+          ...!kept.flows && Array.isArray(s.flows) ? { flows: s.flows } : {}
+        };
+      }
+      const arch = model;
+      if (arch.narrative || arch.flows?.length)
+        markdown = renderArchitecturePage(doku, {
+          narrative: arch.narrative ?? null,
+          flows: arch.flows ?? []
+        });
     } else if (page.kind === "entry") {
       model = { ...page.model, categories };
       if (opts.llm && page.polishable) {
         try {
-          const narrative = (await opts.llm.complete({
+          const narrative2 = (await opts.llm.complete({
             system: ENTRY_NARRATIVE_SYSTEM,
             prompt: page.markdown,
-            maxTokens: 1200
+            maxTokens: 2500
           })).trim();
-          if (narrative) {
-            model = { ...model, narrative };
-            markdown = renderEntryPage(doku, "brainjar-doku/", narrative);
+          if (narrative2) {
+            model = { ...model, narrative: narrative2 };
             polished = true;
+            ok2 = true;
           }
         } catch {
         }
-      }
-    } else if (opts.llm && page.polishable) {
-      try {
-        const synth = parseDocPage(
-          await opts.llm.complete({
-            system: PAGE_SYSTEM,
-            prompt: [
-              "Categories (pick exactly one key):",
-              ...categories.length ? categories.map(
-                (c) => `- ${c.key}: ${c.name} (${c.description})`
-              ) : ["- general: General (everything)"],
-              "",
-              "Fact sheet:",
-              page.markdown
-            ].join("\n"),
-            maxTokens: 2500
-          }),
-          categoryKeys.length ? categoryKeys : ["general"]
-        );
-        if (synth) {
-          const title = pickDocTitle(
-            synth.title,
-            page.title,
-            page.slug,
-            takenTitle
-          );
-          const f = {
-            ...page.model,
-            body: synth.body,
-            docTitle: title,
-            category: synth.category
-          };
-          model = f;
-          markdown = renderFeaturePage(f);
-          page.title = title;
-          polished = true;
+        if (!ok2 && sameFacts) {
+          const s = stored;
+          if (typeof s.narrative === "string" && s.narrative.trim())
+            model = { ...model, narrative: s.narrative };
         }
-      } catch {
       }
+      const narrative = model.narrative;
+      if (narrative)
+        markdown = renderEntryPage(doku, "brainjar-doku/", narrative);
+    } else if (opts.llm && page.polishable) {
       try {
         const { flow } = parseFlow(
           await opts.llm.complete({
@@ -14912,7 +16005,123 @@ async function generateDokuInner(brainId, opts = {}) {
           console.warn(`doku: feature flow failed (${page.slug}):`, e);
         }
       }
+      try {
+        const diagrams = model;
+        const shared = endpointFacts.filter(
+          (e) => e.slug !== page.slug && page.markdown.includes(e.path)
+        );
+        const sharedLines = shared.map(
+          (e) => `- ${e.method} ${e.path}: ${e.summary}${e.auth ? ` Authentication: ${e.auth}` : ""} (page: ${e.slug}, "${e.title}")`
+        );
+        const ctx = {
+          factSheet: [page.markdown, ...sharedLines].join("\n"),
+          hasFlowDiagram: Boolean(diagrams.flowDiagram),
+          hasFlow: Boolean(diagrams.flow)
+        };
+        const prompt = [
+          "Categories (pick exactly one key):",
+          ...categories.length ? categories.map((c) => `- ${c.key}: ${c.name} (${c.description})`) : ["- general: General (everything)"],
+          "",
+          "Available diagrams (the only allowed flow block sources):",
+          ...ctx.hasFlowDiagram ? [
+            `- flowDiagram: "${diagrams.flowDiagram.title}" (the feature's runtime flow, lanes and stations)`
+          ] : [],
+          ...ctx.hasFlow && !ctx.hasFlowDiagram ? ["- flow: the feature's runtime steps as a simple chain"] : [],
+          ...!ctx.hasFlowDiagram && !ctx.hasFlow ? ["- (none)"] : [],
+          "",
+          ...sharedLines.length ? [
+            "Documented elsewhere for the same endpoint (proven facts; reuse them, link the page):",
+            ...sharedLines,
+            ""
+          ] : [],
+          "Fact sheet:",
+          page.markdown
+        ].join("\n");
+        const keys = categoryKeys.length ? categoryKeys : ["general"];
+        let synth = parseDocPage(
+          await opts.llm.complete({
+            system: PAGE_SYSTEM,
+            prompt,
+            maxTokens: 7e3
+          }),
+          keys,
+          ctx
+        );
+        if (!synth.page) {
+          console.warn(
+            `doku: page rejected (${page.slug}): ${synth.error}; retrying once`
+          );
+          synth = parseDocPage(
+            await opts.llm.complete({
+              system: PAGE_SYSTEM,
+              prompt,
+              maxTokens: 1e4
+            }),
+            keys,
+            ctx
+          );
+        }
+        if (synth.dropped.length)
+          console.warn(
+            `doku: blocks dropped (${page.slug}): ${synth.dropped.join("; ")}`
+          );
+        if (synth.page) {
+          const title = pickDocTitle(
+            synth.page.title,
+            page.title,
+            page.slug,
+            takenTitle
+          );
+          const f = {
+            ...model,
+            presentation: synth.page.presentation,
+            docTitle: title,
+            category: synth.page.category
+          };
+          f.body = pageBody(f);
+          model = f;
+          markdown = renderFeaturePage(f);
+          page.title = title;
+          icon = synth.page.icon;
+          polished = true;
+          ok2 = true;
+        } else {
+          console.warn(
+            `doku: page rejected twice (${page.slug}): ${synth.error}`
+          );
+        }
+      } catch (e) {
+        console.warn(`doku: page synthesis failed (${page.slug}):`, e);
+      }
+      if (!ok2 && sameFacts && aiComplete("feature", stored)) {
+        const s = stored;
+        const fresh = model;
+        const f = {
+          ...model,
+          ...s.presentation ? { presentation: s.presentation } : {},
+          body: s.body ?? null,
+          docTitle: s.docTitle ?? null,
+          category: s.category ?? null,
+          ...!fresh.flow && s.flow ? { flow: s.flow } : {},
+          ...!fresh.flowDiagram && s.flowDiagram ? { flowDiagram: s.flowDiagram } : {}
+        };
+        model = f;
+        markdown = renderFeaturePage(f);
+        if (f.docTitle) page.title = f.docTitle;
+      }
+      if (!ok2) {
+        const s = stored;
+        const m = model;
+        if (typeof m.category !== "string" && typeof s?.category === "string" && categoryKeys.includes(s.category))
+          model = { ...model, category: s.category };
+      }
     }
+    model = {
+      ...model,
+      factHash,
+      aiIncomplete: required ? !ok2 : !aiComplete(page.kind, model),
+      aiAttempts: required && !ok2 ? (sameFacts ? state.aiAttempts : 0) + 1 : 0
+    };
     if (page.kind === "feature") {
       const m = model;
       const f = page.model;
@@ -14924,15 +16133,68 @@ async function generateDokuInner(brainId, opts = {}) {
         category: typeof m.category === "string" ? m.category : null
       });
     }
-    await repo.saveDocPage({
+    await save({
       slug: page.slug,
       kind: page.kind,
       title: page.title,
       model,
       markdown,
-      sourceHash
+      sourceHash,
+      icon
     });
-    written++;
+  }
+  if (opts.llm && categoryKeys.length) {
+    const candidates = featureInfo.filter(
+      (f) => taxonomyChanged || opts.retaxonomy || !f.category || !categoryKeys.includes(f.category)
+    );
+    if (candidates.length) {
+      try {
+        const filed = parseRefile(
+          await opts.llm.complete({
+            system: REFILE_SYSTEM,
+            prompt: [
+              "Categories:",
+              ...categories.map(
+                (c) => `- ${c.key}: ${c.name} (${c.description})`
+              ),
+              "",
+              "Pages:",
+              ...candidates.map(
+                (f) => `- ${f.slug}: ${f.title}: ${firstSentence(f.what)}`
+              )
+            ].join("\n"),
+            maxTokens: Math.min(16e3, 300 + candidates.length * 60)
+          }),
+          candidates.map((f) => f.slug),
+          categoryKeys
+        );
+        if (filed) {
+          const unfiled = candidates.filter((f) => !filed[f.slug]).length;
+          if (unfiled)
+            console.warn(
+              `doku: re-filing left ${unfiled} of ${candidates.length} pages as they were`
+            );
+          for (const f of candidates) {
+            const key = filed[f.slug];
+            if (!key || key === f.category) continue;
+            const row = storedRows.get(f.slug);
+            const prev = meta.get(f.slug);
+            if (!row) continue;
+            f.category = key;
+            await save({
+              slug: f.slug,
+              kind: "feature",
+              title: row.title,
+              model: { ...row.model, category: key },
+              markdown: row.markdown,
+              sourceHash: prev?.source_hash ?? sha1(row.markdown)
+            });
+          }
+        } else console.warn("doku: re-filing rejected (invalid reply)");
+      } catch (e) {
+        console.warn("doku: re-filing failed:", e);
+      }
+    }
   }
   for (const c of categories) {
     const members = featureInfo.filter((f) => f.category === c.key).sort((a, b) => a.title.localeCompare(b.title)).map(({ slug: slug2, title, what, updated }) => ({
@@ -14952,11 +16214,18 @@ async function generateDokuInner(brainId, opts = {}) {
       body: null,
       members
     };
-    const sourceHash = sha1(renderCategoryPage(catModel) + "c1");
+    const factHash = sha1(renderCategoryPage(catModel));
+    const sourceHash = sha1(renderCategoryPage(catModel) + "c2");
     const prev = meta.get(slug);
-    const storedBody = storedBySlug.get(slug)?.body;
-    if (prev && !prev.deleted && prev.source_hash === sourceHash && !(opts.llm && typeof storedBody !== "string"))
-      continue;
+    const stored = storedBySlug.get(slug);
+    const state = aiState(stored);
+    const unchanged = Boolean(
+      prev && !prev.deleted && prev.source_hash === sourceHash
+    );
+    const retry = Boolean(opts.llm) && unchanged && !aiComplete("category", stored) && (state.aiAttempts < MAX_AI_ATTEMPTS || Boolean(opts.forceRetry));
+    if (unchanged && !retry) continue;
+    const sameFacts = stored !== void 0 && state.factHash === factHash;
+    let ok2 = !opts.llm;
     if (opts.llm) {
       try {
         const body = parseCategoryBody(
@@ -14971,28 +16240,37 @@ async function generateDokuInner(brainId, opts = {}) {
                 (m) => `- ${m.slug}: ${m.title}: ${firstSentence(m.what)}`
               )
             ].join("\n"),
-            // Weaving 15+ member links into prose needs room; a clipped body loses its
-            // trailing links and voids the story.
-            maxTokens: 2e3
+            // Structured markdown for a large area needs room; a clipped body would
+            // lose its last sections.
+            maxTokens: 4e3
           }),
           members.map((m) => m.slug)
         );
         if (body) {
           catModel.body = body;
           polished = true;
+          ok2 = true;
         }
       } catch {
       }
+      if (!ok2 && sameFacts) {
+        const s = stored;
+        if (typeof s.body === "string" && s.body.trim()) catModel.body = s.body;
+      }
     }
-    await repo.saveDocPage({
+    await save({
       slug,
       kind: "category",
       title: c.name,
-      model: catModel,
+      model: {
+        ...catModel,
+        factHash,
+        aiIncomplete: opts.llm ? !ok2 : !catModel.body,
+        aiAttempts: opts.llm && !ok2 ? (sameFacts ? state.aiAttempts : 0) + 1 : 0
+      },
       markdown: renderCategoryPage(catModel),
       sourceHash
     });
-    written++;
   }
   let deleted = 0;
   for (const [slug, m] of meta) {
@@ -15061,7 +16339,7 @@ async function exportDoku(brainId, root) {
   const sync = await writeDokuTree(root, files);
   return { pages: files.length, ...sync };
 }
-var DOKU_FILENAME, DOKU_DIR, MANIFEST, CHANGELOG_DAYS, sha1, exists, isModule, moduleName, isRepoPath, normPath, PAGE_SYSTEM, TAXONOMY_SYSTEM, CATEGORY_SYSTEM, ENTRY_NARRATIVE_SYSTEM, FLOW_SYSTEM, ARCH_SYSTEM, ARCH_FLOWS_SYSTEM, FEATURE_FLOW_SYSTEM, normTitle2, generateDoku;
+var DOKU_FILENAME, DOKU_DIR, MANIFEST, CHANGELOG_DAYS, sha1, exists, isModule, moduleName, isRepoPath, normPath, MAX_AI_ATTEMPTS, PAGE_SYSTEM, TAXONOMY_SYSTEM, REFILE_SYSTEM, CATEGORY_SYSTEM, ENTRY_NARRATIVE_SYSTEM, FLOW_SYSTEM, ARCH_SYSTEM, ARCH_FLOWS_SYSTEM, FEATURE_FLOW_SYSTEM, normTitle2, generateDoku;
 var init_doku = __esm({
   "packages/ingest/src/doku.ts"() {
     "use strict";
@@ -15072,7 +16350,7 @@ var init_doku = __esm({
     DOKU_DIR = "brainjar-doku";
     MANIFEST = ".manifest.json";
     CHANGELOG_DAYS = 60;
-    sha1 = (s) => createHash2("sha1").update(s).digest("hex");
+    sha1 = (s) => createHash3("sha1").update(s).digest("hex");
     exists = (p) => stat(p).then(
       () => true,
       () => false
@@ -15081,41 +16359,57 @@ var init_doku = __esm({
     moduleName = (o) => String(o.body.name ?? o.title);
     isRepoPath = (name) => !/^([a-zA-Z]:[/\\]|[/\\])/.test(name) && !name.includes("node_modules") && !name.includes(".claude/");
     normPath = (p) => p.replace(/\\/g, "/").replace(/^\.\//, "").toLowerCase();
+    MAX_AI_ATTEMPTS = 3;
     PAGE_SYSTEM = [
       "You write the documentation page for ONE feature, from its fact sheet.",
-      'Respond ONLY with a JSON object of exactly this shape: {"title": "...", "category": "...", "body": "..."}. No code fences, nothing outside the JSON.',
+      'Respond ONLY with a JSON object of exactly this shape: {"title": "...", "category": "...", "icon": "...", "summary": "...", "blocks": [...]}. No code fences, nothing outside the JSON.',
+      '"icon" is exactly ONE emoji that a reader would associate with this feature (a lock for auth, a magnifying glass for search, a bell for notifications); never text.',
       '"title" is a short human page title in product language (a name, not a sentence): never a file path, commit message, or code identifier.',
       '"category" is EXACTLY one key from the category list given with the input; pick the best fit, never invent a key.',
-      '"body" is the page content as markdown (## headings, paragraphs, lists, tables where they help). Every doc is INDIVIDUAL: compose the sections this content needs, never a fixed template.',
-      "A feature exposing an API documents what it is, why you need it, and the endpoints or tools with their parameters. A user-facing feature explains what is shown, why it exists, and how to use it. A pipeline explains what goes in, what comes out, and when it runs. A feature containing several of these covers each of them.",
-      "Open with what the reader can DO or GET with this feature (the outcome), then the mechanics.",
-      "Keep every fact; invent nothing. Do not repeat the change history (it is appended separately). No H1 heading (the title renders above).",
+      '"summary" is 1-2 plain sentences (at most 240 characters) saying what the reader can DO or GET with this feature. It opens the page; it never replaces the description.',
+      '"blocks" is the page content as an ordered list of content blocks; the app decides layout and colors. Each block is an object with "kind", one of:',
+      '{"kind":"text","title":"...","markdown":"..."}: the explanation itself, in full prose: as many connected paragraphs as the subject needs, ### subheadings (never # or ##; "title" is the section heading), lists, inline code, links. The feature description LIVES in text blocks; several text blocks may alternate with other kinds.',
+      '{"kind":"steps","title":"...","items":[{"title":"...","body":"..."}]}: only for a real sequence of actions a person performs (setup, usage, an operator workflow), never for numbering facts.',
+      '{"kind":"table","title":"...","columns":["..."],"rows":[["..."]]}: settings, parameters, error cases, or differences where the columns enable a real comparison. Every row has exactly as many cells as there are columns. Never a table for a single sentence.',
+      '{"kind":"endpoint","method":"GET","path":"/...","summary":"...","auth":"..."}: one concrete HTTP endpoint, ONLY when the fact sheet names that exact method and path; "auth" only when the fact sheet states the authentication. Never derive an endpoint from a file name or a feature title.',
+      '{"kind":"code","title":"...","language":"bash","code":"...","illustrative":true}: a request, response, or command example. Illustrative examples use placeholders such as <API_TOKEN>, never real keys or private content, and never show behavior the fact sheet does not state.',
+      '{"kind":"callout","tone":"note","text":"..."}: one short prerequisite, effect, or limit. "warning" only for a concrete consequence the reader must avoid; otherwise "note".',
+      `{"kind":"flow","title":"...","source":"flowDiagram"}: places the feature's existing runtime diagram where it helps the explanation; allowed only when the input lists that diagram as available, at most once.`,
+      "Composition: explanation and outcome before technical detail. A feature exposing an API documents what it is, why you need it, and each endpoint with its parameters, request and response shape, and error cases, all from the facts only. A user-facing feature explains what is shown and how to use it, with steps only for a real action sequence. A pipeline explains what goes in, what comes out, and when it runs. A configuration-heavy feature tabulates its settings and explains precedence and effects. A feature containing several of these covers each. Mix kinds freely; there is no fixed template and no fixed number of blocks.",
+      "Length follows the subject: an extensive feature gets several text sections with subheadings, the relationships, prerequisites, special cases, and reasons explained, and a concrete example; a small feature stays short. Never break a coherent explanation into bullet points for layout reasons and never cut it short. Explain a term at its first use; state the concrete consequence for the reader.",
+      "Keep every fact; invent nothing. Missing facts stay missing: leave optional blocks out, and when an indispensable piece of information is not available, say so in one plain sentence addressed to the reader (for example: The exact request path is not documented yet.), never mentioning a fact sheet, an input, or a model. Do not repeat the change history or the decision list (both are shown separately). No H1 heading (the title renders above).",
+      "When the input lists facts documented elsewhere for the SAME endpoint or interface, use them: they are proven, so the endpoint may be shown here as well, and the other page may be linked with a short readable link text in the form [text](page:slug), copying the slug exactly. Never merge pages because their titles look alike.",
       PROSE_STYLE
     ].join(" ");
     TAXONOMY_SYSTEM = [
       "You maintain the category structure of a software product's documentation.",
       "You are given the product's feature list and the EXISTING categories (possibly empty).",
       'Respond ONLY with a JSON object of exactly this shape: {"categories": [{"key": "...", "name": "...", "description": "..."}]}. No code fences, nothing outside the JSON.',
-      "Between 3 and 8 categories. Product language a new product manager understands, never code module names.",
+      "The NUMBER of categories follows the product: one distinct area of the product is one category. A small product may need one or two; a large one may need more than eight. Never one category per feature, never a category for a single page when it belongs to an existing area, and never padding to reach a count. Product language a new product manager understands, never code module names.",
       "STABILITY WINS: keep every existing category (same key, same name) that still fits; only add a category when several features fit nothing, only rename or drop on clear misfit.",
       "Group low-level technical internals (schema files, build plumbing) into ONE category rather than spreading them.",
-      '"key" is a short kebab-case identifier; "description" is 1-2 sentences on what the area covers, it doubles as the landing-page intro.',
+      '"key" is a short kebab-case identifier; "description" is ONE short plain sentence (at most 120 characters) saying what the area is for, written for a reader who does not know the product; the details belong to the category page, not here.',
       PROSE_STYLE
     ].join(" ");
+    REFILE_SYSTEM = [
+      "You file documentation pages into the given categories of a software product.",
+      'Respond ONLY with a JSON object of exactly this shape: {"pages": {"<slug>": "<category key>"}}. No code fences, nothing outside the JSON.',
+      "Cover EVERY listed slug exactly once with exactly one key from the category list; choose by the page's subject as its title and summary describe it. Never invent keys or slugs."
+    ].join(" ");
     CATEGORY_SYSTEM = [
-      "You write the landing page for ONE documentation category: the story of this product area.",
-      "You are given the category (name, description) and its member pages (slug, title, summary).",
-      "Respond with 2-6 plain markdown paragraphs (no headings, no lists) telling how this area works as a whole: what it solves and how its parts play together.",
-      "Weave EVERY member page into the text as an inline markdown link, exactly the form [Title](page:slug), copying the slug character for character from the input, so the reader follows links from the sentence they are reading.",
-      "Ground everything in the given summaries; invent nothing.",
+      "You write the overview page for ONE documentation category: what this product area does, how its parts relate, and what a reader needs to know before opening a page.",
+      "You are given the category (name, description) and its member pages (slug, title, summary). The complete member list is rendered separately below your text, so you never have to mention every page.",
+      "Respond with structured markdown: an opening paragraph, then ## and ### headings with as many paragraphs as the subject needs, and lists only where they help. Explain the area's job, the relationships between its parts, prerequisites, limits, and terms at first use. Long is fine when the content needs it; never pad a small area.",
+      "Link a page only where the link helps the reader at that point, with a short readable link text, exactly the form [text](page:slug), copying the slug character for character from the input. Never invent a slug and never turn a page title into a new page.",
+      "No H1 heading (the category name renders above). Ground everything in the given summaries; invent nothing.",
       PROSE_STYLE
     ].join(" ");
     ENTRY_NARRATIVE_SYSTEM = [
       "You write the opening description for a software project's documentation.",
       "You are given the documentation entry page (the project's feature list) as markdown.",
-      "Respond with 4-7 short plain-text paragraphs a newcomer understands, covering in order: what the project IS and the problem it solves and for whom; what it DOES (the core loop in plain words); its SURFACES and integrations (the ways people and tools connect to it); and how the pieces fit together.",
+      "Respond in markdown: first one short plain paragraph saying what the project IS and for whom, then ## sections a newcomer understands, covering in order: the problem it solves; what it DOES (the core loop in plain words); its SURFACES and integrations (the ways people and tools connect to it); and how the pieces fit together. Paragraphs carry the explanation; a list only where items are truly parallel.",
       "Complete enough that the reader could present the product afterwards, without descending into single-feature detail.",
-      "Ground every statement in the given features; invent nothing, no marketing superlatives, no headings, no lists.",
+      "Ground every statement in the given features; invent nothing, no marketing superlatives, no H1 heading.",
       PROSE_STYLE
     ].join(" ");
     FLOW_SYSTEM = [
@@ -15137,7 +16431,8 @@ var init_doku = __esm({
     ].join(" ");
     ARCH_FLOWS_SYSTEM = [
       "You read one architecture overview of a software system (module groups with their features and dependencies, plus real file paths) and produce the system's main RUNTIME flows: how a request, session, or piece of data actually moves through the system.",
-      'Respond ONLY with JSON of exactly this shape: {"flows": [{"slug": "...", "title": "...", "summary": "...", "lanes": [{"key": "...", "title": "..."}], "nodes": [{"id": "...", "lane": "...", "title": "...", "subtitle": "...", "kind": "...", "evidence": ["path"]}], "edges": [{"from": "...", "to": "...", "label": "...", "kind": "..."}]}]}. No markdown, nothing outside the JSON.',
+      'Respond ONLY with JSON of exactly this shape: {"flows": [{"slug": "...", "title": "...", "summary": "...", "explanation": "...", "lanes": [{"key": "...", "title": "..."}], "nodes": [{"id": "...", "lane": "...", "title": "...", "subtitle": "...", "kind": "...", "evidence": ["path"]}], "edges": [{"from": "...", "to": "...", "label": "...", "kind": "..."}]}]}. Nothing outside the JSON.',
+      '"explanation" walks a reader through THIS flow in markdown (2-5 short paragraphs, ### subheadings where they help, at most 3500 characters): what starts it, what each phase does, what comes out. Describe an order only where the edges show it; where paths run in parallel or depend on a gate, say so instead of inventing a sequence. Name the same stations as the nodes.',
       "Produce 2 to 4 flows, one per MAIN runtime path a newcomer must understand (for example: how input becomes stored data, how a query becomes an answer, how an external agent connects, how background verification runs). Cover every major path the features support; do not stop at two when the system clearly has more.",
       "lanes are 3-5 PHASES of the flow in order (intake, processing, storage, ...), titled in plain words. Never folder names.",
       "nodes are the runtime components in those phases: 4-10 per flow. kind is exactly one of: actor (human or external agent), surface (UI or endpoint), logic (application work), policy (a gate: auth, quota, validation), action (an outward call such as an LLM or external API), data (a store). title at most 3 words; subtitle at most 3 words (under 24 characters).",
@@ -15272,10 +16567,12 @@ var init_verify_agent = __esm({
     init_sdk();
     init_src2();
     init_src();
+    init_allowance();
     init_product_facts();
     init_doku();
     init_llm();
     init_openai();
+    init_provider_rate2();
     init_routing();
     VERIFY_SYSTEM = [
       "You are BrainJar's verification agent. You read a software repository and record durable product knowledge, with one iron rule: prose is never truth, code is.",
@@ -15301,9 +16598,9 @@ var init_verify_agent = __esm({
   }
 });
 
-// packages/ingest/src/verify-poll.ts
-var init_verify_poll = __esm({
-  "packages/ingest/src/verify-poll.ts"() {
+// packages/ingest/src/verify-start.ts
+var init_verify_start = __esm({
+  "packages/ingest/src/verify-start.ts"() {
     "use strict";
     init_src2();
     init_src();
@@ -15312,14 +16609,49 @@ var init_verify_poll = __esm({
   }
 });
 
-// packages/ingest/src/verify-start.ts
-var init_verify_start = __esm({
-  "packages/ingest/src/verify-start.ts"() {
+// packages/ingest/src/verify-poll.ts
+var init_verify_poll = __esm({
+  "packages/ingest/src/verify-poll.ts"() {
     "use strict";
     init_src2();
     init_src();
     init_repo_reader();
     init_verify_agent();
+    init_verify_start();
+  }
+});
+
+// packages/ingest/src/scheduler.ts
+var init_scheduler = __esm({
+  "packages/ingest/src/scheduler.ts"() {
+    "use strict";
+    init_src2();
+    init_daily_log();
+    init_summaries();
+  }
+});
+
+// packages/ingest/src/job-worker.ts
+var init_job_worker = __esm({
+  "packages/ingest/src/job-worker.ts"() {
+    "use strict";
+    init_src2();
+    init_deepscan();
+    init_doku();
+    init_scheduler();
+    init_summaries();
+    init_verify_poll();
+    init_routing();
+    init_allowance();
+    init_verify_start();
+  }
+});
+
+// packages/ingest/src/job-clock.ts
+var init_job_clock = __esm({
+  "packages/ingest/src/job-clock.ts"() {
+    "use strict";
+    init_src2();
   }
 });
 
@@ -15330,18 +16662,10 @@ var init_ask_agent_model = __esm({
     init_sdk();
     init_src2();
     init_src();
+    init_allowance();
     init_llm();
     init_openai();
-  }
-});
-
-// packages/ingest/src/scheduler.ts
-var init_scheduler = __esm({
-  "packages/ingest/src/scheduler.ts"() {
-    "use strict";
-    init_src2();
-    init_daily_log();
-    init_summaries();
+    init_provider_rate2();
   }
 });
 
@@ -15364,6 +16688,7 @@ var init_src3 = __esm({
     init_llm();
     init_openai();
     init_routing();
+    init_allowance();
     init_rationale_extractor();
     init_extraction();
     init_entities();
@@ -15401,6 +16726,8 @@ var init_src3 = __esm({
     init_verify_agent();
     init_verify_poll();
     init_verify_start();
+    init_job_worker();
+    init_job_clock();
     init_ask_agent_model();
     init_scheduler();
     registerConnector(
@@ -15453,7 +16780,24 @@ async function captureApi(pathAndQuery, init2 = {}) {
   }
   return body;
 }
-var TokenError, TOKEN_HELP;
+async function uploadArtifacts(brain, sourceId, artifacts, cursor3) {
+  let inserted = 0;
+  for (let i = 0; i < artifacts.length; i += UPLOAD_PORTION) {
+    const last = i + UPLOAD_PORTION >= artifacts.length;
+    const r = await captureApi("/capture/artifacts", {
+      method: "POST",
+      body: {
+        brain,
+        sourceId,
+        artifacts: artifacts.slice(i, i + UPLOAD_PORTION),
+        cursor: last ? cursor3 : null
+      }
+    });
+    inserted += r.inserted;
+  }
+  return inserted;
+}
+var TokenError, TOKEN_HELP, UPLOAD_PORTION;
 var init_api_client = __esm({
   "packages/cli/src/api-client.ts"() {
     "use strict";
@@ -15461,6 +16805,7 @@ var init_api_client = __esm({
     TokenError = class extends Error {
     };
     TOKEN_HELP = "BrainJar token revoked or invalid. Create a new token under Account in the web app, then run `npx brainjar init --brain <id> --token <token>` once in any project on this machine.";
+    UPLOAD_PORTION = 2e3;
   }
 });
 
@@ -15693,7 +17038,7 @@ var init_debt = __esm({
 });
 
 // packages/cli/src/adapters/claude-code.ts
-import { createHash as createHash3 } from "node:crypto";
+import { createHash as createHash4 } from "node:crypto";
 function targetOf(input) {
   const i = input ?? {};
   for (const k of ["command", "file_path", "notebook_path"]) {
@@ -15738,7 +17083,7 @@ var init_claude_code = __esm({
     "use strict";
     init_src();
     EDIT_TOOLS = /* @__PURE__ */ new Set(["Edit", "Write", "MultiEdit", "NotebookEdit"]);
-    short2 = (s) => createHash3("sha256").update(s).digest("hex").slice(0, 16);
+    short2 = (s) => createHash4("sha256").update(s).digest("hex").slice(0, 16);
     claudeCode2 = {
       id: "claude-code",
       map(payload, now) {
@@ -15837,7 +17182,7 @@ var init_claude_code = __esm({
 });
 
 // packages/cli/src/adapters/cursor.ts
-import { createHash as createHash4 } from "node:crypto";
+import { createHash as createHash5 } from "node:crypto";
 function targetOf2(input) {
   const i = input ?? {};
   for (const k of ["command", "file_path", "path", "target_file"]) {
@@ -15858,7 +17203,7 @@ var init_cursor = __esm({
   "packages/cli/src/adapters/cursor.ts"() {
     "use strict";
     init_src();
-    short3 = (s) => createHash4("sha256").update(s).digest("hex").slice(0, 16);
+    short3 = (s) => createHash5("sha256").update(s).digest("hex").slice(0, 16);
     cursor2 = {
       id: "cursor",
       map(payload, now) {
@@ -15976,7 +17321,7 @@ var init_cursor = __esm({
 });
 
 // packages/cli/src/adapters/codex.ts
-import { createHash as createHash5 } from "node:crypto";
+import { createHash as createHash6 } from "node:crypto";
 function patchFiles(patch) {
   const out = /* @__PURE__ */ new Set();
   for (const m of patch.matchAll(
@@ -16012,7 +17357,7 @@ var init_codex = __esm({
     "use strict";
     init_src();
     PATCH_TOOLS = /* @__PURE__ */ new Set(["apply_patch", "Edit", "Write"]);
-    short4 = (s) => createHash5("sha256").update(s).digest("hex").slice(0, 16);
+    short4 = (s) => createHash6("sha256").update(s).digest("hex").slice(0, 16);
     codex2 = {
       id: "codex",
       map(payload, now) {
@@ -16109,7 +17454,7 @@ var init_codex = __esm({
 });
 
 // packages/cli/src/adapters/copilot.ts
-import { createHash as createHash6 } from "node:crypto";
+import { createHash as createHash7 } from "node:crypto";
 function targetOf3(args) {
   if (!args || typeof args !== "object") return "";
   const a = args;
@@ -16142,7 +17487,7 @@ var init_copilot = __esm({
     "use strict";
     init_src();
     EDIT_TOOLS2 = /* @__PURE__ */ new Set(["edit", "create"]);
-    short5 = (s) => createHash6("sha256").update(s).digest("hex").slice(0, 16);
+    short5 = (s) => createHash7("sha256").update(s).digest("hex").slice(0, 16);
     EVENT_ALIASES = {
       SessionStart: "sessionStart",
       SessionEnd: "sessionEnd",
@@ -16251,7 +17596,7 @@ var init_copilot = __esm({
 });
 
 // packages/cli/src/adapters/gemini.ts
-import { createHash as createHash7 } from "node:crypto";
+import { createHash as createHash8 } from "node:crypto";
 function targetOf4(input) {
   const i = input ?? {};
   for (const k of ["command", "file_path"]) {
@@ -16273,7 +17618,7 @@ var init_gemini = __esm({
     "use strict";
     init_src();
     EDIT_TOOLS3 = /* @__PURE__ */ new Set(["write_file", "replace"]);
-    short6 = (s) => createHash7("sha256").update(s).digest("hex").slice(0, 16);
+    short6 = (s) => createHash8("sha256").update(s).digest("hex").slice(0, 16);
     gemini2 = {
       id: "gemini",
       map(payload, now) {
@@ -16369,7 +17714,7 @@ var init_gemini = __esm({
 });
 
 // packages/cli/src/adapters/kiro.ts
-import { createHash as createHash8 } from "node:crypto";
+import { createHash as createHash9 } from "node:crypto";
 function targetOf5(input) {
   const i = input ?? {};
   for (const k of ["command", "cmd", "path", "file_path", "filePath"]) {
@@ -16400,7 +17745,7 @@ var init_kiro = __esm({
     "use strict";
     init_src();
     EDIT_TOOLS4 = /* @__PURE__ */ new Set(["fs_write", "write", "str_replace", "fs_append"]);
-    short7 = (s) => createHash8("sha256").update(s).digest("hex").slice(0, 16);
+    short7 = (s) => createHash9("sha256").update(s).digest("hex").slice(0, 16);
     EVENTS5 = {
       agentSpawn: "start",
       sessionStart: "start",
@@ -16516,7 +17861,7 @@ var init_kiro = __esm({
 });
 
 // packages/cli/src/adapters/opencode.ts
-import { createHash as createHash9 } from "node:crypto";
+import { createHash as createHash10 } from "node:crypto";
 function commitShas7(text) {
   const out = /* @__PURE__ */ new Set();
   for (const m of (text ?? "").matchAll(/\[[^\]\n]* ([0-9a-f]{7,40})\]/g)) {
@@ -16530,7 +17875,7 @@ var init_opencode = __esm({
     "use strict";
     init_src();
     EDIT_TOOLS5 = /* @__PURE__ */ new Set(["edit", "write"]);
-    short8 = (s) => createHash9("sha256").update(s).digest("hex").slice(0, 16);
+    short8 = (s) => createHash10("sha256").update(s).digest("hex").slice(0, 16);
     opencode2 = {
       id: "opencode",
       map(payload, now) {
@@ -16630,7 +17975,7 @@ var init_opencode = __esm({
 });
 
 // packages/cli/src/adapters/cline.ts
-import { createHash as createHash10 } from "node:crypto";
+import { createHash as createHash11 } from "node:crypto";
 function targetOf6(params) {
   const i = params ?? {};
   for (const k of ["command", "path"]) {
@@ -16646,9 +17991,9 @@ function commitShas8(text) {
   return [...out];
 }
 function stamp2(ts, now) {
-  const n = typeof ts === "string" && /^\d+$/.test(ts) ? Number(ts) : ts;
-  if (typeof n === "number" && Number.isFinite(n))
-    return new Date(n).toISOString();
+  const n2 = typeof ts === "string" && /^\d+$/.test(ts) ? Number(ts) : ts;
+  if (typeof n2 === "number" && Number.isFinite(n2))
+    return new Date(n2).toISOString();
   if (typeof ts === "string" && !Number.isNaN(Date.parse(ts)))
     return new Date(ts).toISOString();
   return now;
@@ -16662,7 +18007,7 @@ var init_cline = __esm({
     "use strict";
     init_src();
     EDIT_TOOLS6 = /* @__PURE__ */ new Set(["write_to_file", "replace_in_file", "apply_patch"]);
-    short9 = (s) => createHash10("sha256").update(s).digest("hex").slice(0, 16);
+    short9 = (s) => createHash11("sha256").update(s).digest("hex").slice(0, 16);
     CLINE_REPLY = JSON.stringify({ cancel: false });
     cline2 = {
       id: "cline",
@@ -16860,16 +18205,12 @@ async function linkForSpool(file) {
 async function shipSpool(file, link) {
   const events = readSpool(file);
   if (!events.length) return;
-  const r = await captureApi("/capture/events", {
+  await captureApi("/capture/events", {
     method: "POST",
-    body: {
-      brain: link.brainId,
-      events,
-      author: loadEnv().BRAINJAR_AUTHOR?.trim() || null
-    }
+    body: { brain: link.brainId, events }
   });
   console.error(
-    `brainjar: session captured \u2014 ${r.prompts ?? 0} intents, ${r.failures ?? 0} failures, ${(r.skippedNoise ?? 0) + (r.skippedFailures ?? 0)} noise skipped` + (r.consolidated ? `, ${r.consolidated} product facts` : "")
+    `brainjar: session sent (${events.length} events), the server reads it in the background`
   );
 }
 function parseHookArgs(argv) {
@@ -16968,23 +18309,16 @@ async function syncRepo(root) {
       const connector = createConnector("git_local", { cwd: root }, {});
       const artifacts = await connector.sync(project.cursor ?? void 0);
       if (artifacts.length > 0) {
-        const r = await captureApi(
-          "/capture/artifacts",
-          {
-            method: "POST",
-            body: {
-              brain: link.brainId,
-              sourceId: project.sourceId,
-              artifacts,
-              cursor: maxUpdatedAt(artifacts) ?? project.cursor
-            }
-          }
+        const inserted = await uploadArtifacts(
+          link.brainId,
+          project.sourceId,
+          artifacts,
+          maxUpdatedAt(artifacts) ?? project.cursor
         );
-        if (r.inserted > 0) {
-          console.error(`brainjar: ${r.inserted} new commits captured`);
-          if (r.linked > 0) {
-            console.error(`brainjar: ${r.linked} session-commit links ensured`);
-          }
+        if (inserted > 0) {
+          console.error(
+            `brainjar: ${inserted} new commits sent, the server reads them in the background`
+          );
           const graph = await scanStructure(root);
           await captureApi("/capture/structure", {
             method: "POST",
@@ -17041,12 +18375,67 @@ var init_sync2 = __esm({
   }
 });
 
+// packages/cli/src/wait.ts
+function progressLine(p) {
+  const left = p.pending > 0 ? `${n(p.pending)} commits and sessions still to read` : `${n(p.queued + p.running)} capture jobs still running`;
+  const queue = p.ahead > 0 ? ` (${n(p.ahead)} jobs of other projects ahead)` : "";
+  return `   \u2026 ${left}${queue}`;
+}
+async function waitForServer(brainId, since, opts = {}) {
+  const poll = opts.poll ?? (() => captureApi(
+    `/capture/progress?brain=${brainId}&since=${encodeURIComponent(since.toISOString())}`
+  ));
+  const sleep3 = opts.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+  const write = opts.write ?? ((s) => void process.stdout.write(s));
+  const tty = opts.tty ?? Boolean(process.stdout.isTTY);
+  const intervalMs = opts.intervalMs ?? 2e3;
+  let shown = "";
+  let shownAt = 0;
+  let misses = 0;
+  for (; ; ) {
+    let p;
+    try {
+      p = await poll();
+      misses = 0;
+    } catch {
+      if (++misses * intervalMs >= 6e4) {
+        if (tty && shown) write("\n");
+        return null;
+      }
+      await sleep3(intervalMs);
+      continue;
+    }
+    if (p.queued + p.running === 0) {
+      if (tty && shown) write("\r\x1B[K");
+      return p;
+    }
+    const line = progressLine(p);
+    if (tty) write(`\r\x1B[K${line}`);
+    else if (line !== shown && Date.now() - shownAt >= 15e3) {
+      write(`${line}
+`);
+      shownAt = Date.now();
+    }
+    shown = line;
+    await sleep3(intervalMs);
+  }
+}
+var n;
+var init_wait = __esm({
+  "packages/cli/src/wait.ts"() {
+    "use strict";
+    init_api_client();
+    n = (x) => x.toLocaleString("en-US");
+  }
+});
+
 // packages/cli/src/init.ts
 var init_exports = {};
 __export(init_exports, {
   init: () => init,
   initMain: () => initMain
 });
+import { hostname } from "node:os";
 import { readFile as readFile12 } from "node:fs/promises";
 async function init(argv) {
   const skipTranscripts = argv.includes("--no-transcripts");
@@ -17056,6 +18445,7 @@ async function init(argv) {
   const tokenFlag = flag("--token");
   const root = await repoRoot();
   const name = repoName(root);
+  const startedAt = new Date(Date.now() - 6e4);
   console.log(`
 \u{1F9E0}  BrainJar init \u2014 ${name}
     repo: ${root}`);
@@ -17083,6 +18473,7 @@ async function init(argv) {
     method: "POST",
     body: {
       name,
+      machine: hostname(),
       ...brainFlag ? { brainId: brainFlag } : reuse ? { brainId: reuse.brainId } : {},
       ...reuse ? { sourceId: reuse.sourceId } : {},
       ...remote ? { remote } : {}
@@ -17104,61 +18495,45 @@ async function init(argv) {
   }
   step(3, "Scanning code + ingesting git history\u2026");
   const graph = await scanStructure(root);
-  const structure = await captureApi(
-    "/capture/structure",
-    { method: "POST", body: { brain: conn.brainId, graph } }
-  );
+  await captureApi("/capture/structure", {
+    method: "POST",
+    body: { brain: conn.brainId, graph }
+  });
   const connector = createConnector("git_local", { cwd: root }, {});
   const artifacts = await connector.sync(conn.cursor ?? void 0);
   let commits = 0;
-  let objects = 0;
   if (artifacts.length > 0) {
-    const r = await captureApi(
-      "/capture/artifacts",
-      {
-        method: "POST",
-        body: {
-          brain: conn.brainId,
-          sourceId: conn.sourceId,
-          artifacts,
-          cursor: maxUpdatedAt(artifacts) ?? conn.cursor
-        }
-      }
+    commits = await uploadArtifacts(
+      conn.brainId,
+      conn.sourceId,
+      artifacts,
+      maxUpdatedAt(artifacts) ?? conn.cursor
     );
-    commits = r.inserted;
-    objects = r.objects;
   }
   ok(
-    `${structure.modules} modules, ${commits} new commits \u2192 ${objects} objects`
+    `${graph.modules.length} modules, ${commits} new commits sent to the server`
   );
   step(4, "Backfilling past agent sessions\u2026");
   if (skipTranscripts) {
     ok("skipped (--no-transcripts)");
   } else {
-    const author = loadEnv().BRAINJAR_AUTHOR?.trim() || null;
     const files = await transcriptFiles(root);
-    let prompts = 0;
-    let failures = 0;
-    let consolidated = 0;
     let truncatedCount = 0;
     let skipped = 0;
     for (const f of files) {
       try {
         const { text, truncated } = capTranscript(await readFile12(f, "utf8"));
         if (truncated) truncatedCount++;
-        const r = await captureApi("/capture/transcript", {
+        await captureApi("/capture/transcript", {
           method: "POST",
-          body: { brain: conn.brainId, text, author, backfill: true }
+          body: { brain: conn.brainId, text, backfill: true }
         });
-        prompts += r.prompts;
-        failures += r.failures;
-        consolidated += r.consolidated;
       } catch {
         skipped++;
       }
     }
     ok(
-      `${files.length - skipped} sessions \u2192 ${prompts} reasoning, ${failures} failures` + (consolidated ? `, ${consolidated} product facts` : "") + " captured" + (truncatedCount ? ` (${truncatedCount} oversized, newest 40MB kept)` : "") + (skipped ? `, ${skipped} skipped on errors` : "")
+      `${files.length - skipped} sessions sent to the server` + (truncatedCount ? ` (${truncatedCount} oversized, newest 40MB kept)` : "") + (skipped ? `, ${skipped} skipped on errors` : "")
     );
   }
   step(5, "Semantic search\u2026");
@@ -17208,6 +18583,15 @@ async function init(argv) {
   } catch {
     ok("skipped (could not write the pointer)");
   }
+  step(8, "Filling the Brain on the server\u2026");
+  console.log("   Stopping this (Ctrl+C) is safe: the server keeps working.");
+  const filled = await waitForServer(conn.brainId, startedAt);
+  if (!filled) ok("lost the connection to the server; it keeps working");
+  else if (filled.failed > 0)
+    ok(
+      `done; ${filled.failed} capture jobs failed for good (see the bell in the web app)`
+    );
+  else ok("done");
   try {
     await captureApi("/capture/connect", {
       method: "POST",
@@ -17215,6 +18599,7 @@ async function init(argv) {
         brainId: conn.brainId,
         sourceId: conn.sourceId,
         name,
+        machine: hostname(),
         done: true,
         tools: tools.map((t) => t.id)
       }
@@ -17254,8 +18639,9 @@ var init_init = __esm({
     init_src();
     init_api_client();
     init_sync2();
-    step = (n, msg) => console.log(`
-[${n}/7] ${msg}`);
+    init_wait();
+    step = (n2, msg) => console.log(`
+[${n2}/8] ${msg}`);
     ok = (msg) => console.log(`   \u2713 ${msg}`);
   }
 });
@@ -17528,13 +18914,13 @@ function selectDeepScanFiles(candidates, graph, maxFiles = MAX_FILES) {
     }
   };
   for (const bucket of BUCKET_CAPS) {
-    let n = 0;
+    let n2 = 0;
     const ordered = [...candidates].sort().reverse();
     for (const p of ordered) {
-      if (n >= bucket.cap) break;
+      if (n2 >= bucket.cap) break;
       if (bucket.test(p) && !has.has(p)) {
         take(p);
-        n++;
+        n2++;
       }
     }
   }