@imagile-dev/toil 0.1.0-alpha.4 → 0.1.0-alpha.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/toil-lib.js CHANGED
@@ -1,7 +1,7 @@
1
1
  import { createRequire as __toilCreateRequire } from 'node:module';
2
2
  const require = __toilCreateRequire(import.meta.url);
3
- const __TOIL_VERSION__ = "0.1.0-alpha.4"; // x-release-please-version
4
- const __TOIL_COMMIT__ = "e26c448fcef2a5529f41d6ed9b1fa1bfb8c0f9b3"; // toil-build-commit
3
+ const __TOIL_VERSION__ = "0.1.0-alpha.5"; // x-release-please-version
4
+ const __TOIL_COMMIT__ = "18c02b1a5d7e734dbf01449c08613a46c857ca01"; // toil-build-commit
5
5
  var __create = Object.create;
6
6
  var __defProp = Object.defineProperty;
7
7
  var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
@@ -15283,9 +15283,9 @@ var require_internal = __commonJS({
15283
15283
  }
15284
15284
  InternalCodec.prototype.encoder = InternalEncoder;
15285
15285
  InternalCodec.prototype.decoder = InternalDecoder;
15286
- var StringDecoder = __require("string_decoder").StringDecoder;
15286
+ var StringDecoder2 = __require("string_decoder").StringDecoder;
15287
15287
  function InternalDecoder(options2, codec2) {
15288
- this.decoder = new StringDecoder(codec2.enc);
15288
+ this.decoder = new StringDecoder2(codec2.enc);
15289
15289
  }
15290
15290
  InternalDecoder.prototype.write = function(buf) {
15291
15291
  if (!Buffer3.isBuffer(buf)) {
@@ -21782,20 +21782,20 @@ var require_typed_parameter = __commonJS({
21782
21782
  microseconds
21783
21783
  };
21784
21784
  }
21785
- const match = TIME_PATTERN.exec(String(value2));
21786
- if (!match) {
21785
+ const match2 = TIME_PATTERN.exec(String(value2));
21786
+ if (!match2) {
21787
21787
  throw new TypeError(
21788
21788
  `TIME parameter must be 'HH:MM:SS[.ffffff]' or milliseconds, got ${JSON.stringify(String(value2))}`
21789
21789
  );
21790
21790
  }
21791
- const hours = Number(match[2]);
21791
+ const hours = Number(match2[2]);
21792
21792
  return {
21793
- negative: Boolean(match[1]),
21793
+ negative: Boolean(match2[1]),
21794
21794
  days: Math.floor(hours / 24),
21795
21795
  hours: hours % 24,
21796
- minutes: Number(match[3]),
21797
- seconds: Number(match[4]),
21798
- microseconds: match[5] ? Number(match[5].padEnd(6, "0")) : 0
21796
+ minutes: Number(match2[3]),
21797
+ seconds: Number(match2[4]),
21798
+ microseconds: match2[5] ? Number(match2[5].padEnd(6, "0")) : 0
21799
21799
  };
21800
21800
  }
21801
21801
  function timeEncoder() {
@@ -37377,13 +37377,13 @@ var require_ezConnectResolver = __commonJS({
37377
37377
  const urlWithoutWhiteSpaces = url2.replace(/\s/g, "");
37378
37378
  let bool = 0;
37379
37379
  let protocol = null, hostInfo = null, serviceName = null, serverMode = null, instanceName = null;
37380
- for (const match of urlWithoutWhiteSpaces.matchAll(EZ_URL_PATTERN)) {
37380
+ for (const match2 of urlWithoutWhiteSpaces.matchAll(EZ_URL_PATTERN)) {
37381
37381
  bool = 1;
37382
- protocol = match.groups.protocol;
37383
- hostInfo = match.groups.hostinfo;
37384
- serviceName = match.groups.servicename;
37385
- serverMode = match.groups.servermode;
37386
- instanceName = match.groups.instance;
37382
+ protocol = match2.groups.protocol;
37383
+ hostInfo = match2.groups.hostinfo;
37384
+ serviceName = match2.groups.servicename;
37385
+ serverMode = match2.groups.servermode;
37386
+ instanceName = match2.groups.instance;
37387
37387
  }
37388
37388
  if (!bool) {
37389
37389
  errors.throwErr(errors.ERR_INVALID_EZCONNECT_SYNTAX, "input string not in easy connect format", urlWithoutWhiteSpaces);
@@ -37472,9 +37472,9 @@ var require_ezConnectResolver = __commonJS({
37472
37472
  for (const addressList of addressLists) {
37473
37473
  let addressNodeCount = 0;
37474
37474
  const addressListBuilder = new Array();
37475
- for (const match of addressList.matchAll(HOSTNAMES_PATTERN)) {
37476
- const hostnames = match.groups.hostnames.split(",");
37477
- let port = match.groups.port;
37475
+ for (const match2 of addressList.matchAll(HOSTNAMES_PATTERN)) {
37476
+ const hostnames = match2.groups.hostnames.split(",");
37477
+ let port = match2.groups.port;
37478
37478
  if (port == null) {
37479
37479
  port = "1521";
37480
37480
  }
@@ -58479,10 +58479,10 @@ var require_oracledb = __commonJS({
58479
58479
  parsedUrl = url2.substring(0, url2.indexOf("?"));
58480
58480
  urlExtendedPart = url2.substring(url2.indexOf("?"), url2.length);
58481
58481
  }
58482
- const match = parsedUrl.match(baseRegex);
58483
- if (match) {
58484
- const provider = match.groups.provider;
58485
- const provider_arg = match.groups.provider_arg;
58482
+ const match2 = parsedUrl.match(baseRegex);
58483
+ if (match2) {
58484
+ const provider = match2.groups.provider;
58485
+ const provider_arg = match2.groups.provider_arg;
58486
58486
  const hookFn = registeredConfigProviderHooks[provider];
58487
58487
  if (hookFn == void 0)
58488
58488
  errors.throwErr(errors.ERR_REGISTER_HOOKFN_CONFIGPROVIDER, provider);
@@ -61038,19 +61038,19 @@ var require_result = __commonJS({
61038
61038
  }
61039
61039
  // adds a command complete message
61040
61040
  addCommandComplete(msg) {
61041
- let match;
61041
+ let match2;
61042
61042
  if (msg.text) {
61043
- match = matchRegexp.exec(msg.text);
61043
+ match2 = matchRegexp.exec(msg.text);
61044
61044
  } else {
61045
- match = matchRegexp.exec(msg.command);
61045
+ match2 = matchRegexp.exec(msg.command);
61046
61046
  }
61047
- if (match) {
61048
- this.command = match[1];
61049
- if (match[3]) {
61050
- this.oid = parseInt(match[2], 10);
61051
- this.rowCount = parseInt(match[3], 10);
61052
- } else if (match[2]) {
61053
- this.rowCount = parseInt(match[2], 10);
61047
+ if (match2) {
61048
+ this.command = match2[1];
61049
+ if (match2[3]) {
61050
+ this.oid = parseInt(match2[2], 10);
61051
+ this.rowCount = parseInt(match2[3], 10);
61052
+ } else if (match2[2]) {
61053
+ this.rowCount = parseInt(match2[2], 10);
61054
61054
  }
61055
61055
  }
61056
61056
  }
@@ -61715,7 +61715,7 @@ var require_serializer = __commonJS({
61715
61715
  buff.writeUInt32BE(rows, buff.length - 4);
61716
61716
  return buff;
61717
61717
  };
61718
- var cancel = (processID, secretKey) => {
61718
+ var cancel2 = (processID, secretKey) => {
61719
61719
  const buffer = Buffer.allocUnsafe(16);
61720
61720
  buffer.writeInt32BE(16, 0);
61721
61721
  buffer.writeInt16BE(1234, 4);
@@ -61793,7 +61793,7 @@ var require_serializer = __commonJS({
61793
61793
  copyData,
61794
61794
  copyDone: () => copyDoneBuffer,
61795
61795
  copyFail,
61796
- cancel
61796
+ cancel: cancel2
61797
61797
  };
61798
61798
  exports.serialize = serialize;
61799
61799
  }
@@ -62472,7 +62472,7 @@ var require_split2 = __commonJS({
62472
62472
  "node_modules/split2/index.js"(exports, module) {
62473
62473
  "use strict";
62474
62474
  var { Transform } = __require("stream");
62475
- var { StringDecoder } = __require("string_decoder");
62475
+ var { StringDecoder: StringDecoder2 } = __require("string_decoder");
62476
62476
  var kLast = /* @__PURE__ */ Symbol("last");
62477
62477
  var kDecoder = /* @__PURE__ */ Symbol("decoder");
62478
62478
  function transform2(chunk, enc3, cb) {
@@ -62552,7 +62552,7 @@ var require_split2 = __commonJS({
62552
62552
  options2.readableObjectMode = true;
62553
62553
  const stream = new Transform(options2);
62554
62554
  stream[kLast] = "";
62555
- stream[kDecoder] = new StringDecoder("utf8");
62555
+ stream[kDecoder] = new StringDecoder2("utf8");
62556
62556
  stream.matcher = matcher;
62557
62557
  stream.mapper = mapper;
62558
62558
  stream.maxLength = options2.maxLength;
@@ -66340,16 +66340,16 @@ var require_sprintf = __commonJS({
66340
66340
  if (sprintf_cache[fmt]) {
66341
66341
  return sprintf_cache[fmt];
66342
66342
  }
66343
- var _fmt = fmt, match, parse_tree = [], arg_names = 0;
66343
+ var _fmt = fmt, match2, parse_tree = [], arg_names = 0;
66344
66344
  while (_fmt) {
66345
- if ((match = re.text.exec(_fmt)) !== null) {
66346
- parse_tree.push(match[0]);
66347
- } else if ((match = re.modulo.exec(_fmt)) !== null) {
66345
+ if ((match2 = re.text.exec(_fmt)) !== null) {
66346
+ parse_tree.push(match2[0]);
66347
+ } else if ((match2 = re.modulo.exec(_fmt)) !== null) {
66348
66348
  parse_tree.push("%");
66349
- } else if ((match = re.placeholder.exec(_fmt)) !== null) {
66350
- if (match[2]) {
66349
+ } else if ((match2 = re.placeholder.exec(_fmt)) !== null) {
66350
+ if (match2[2]) {
66351
66351
  arg_names |= 1;
66352
- var field_list = [], replacement_field = match[2], field_match = [];
66352
+ var field_list = [], replacement_field = match2[2], field_match = [];
66353
66353
  if ((field_match = re.key.exec(replacement_field)) !== null) {
66354
66354
  field_list.push(field_match[1]);
66355
66355
  while ((replacement_field = replacement_field.substring(field_match[0].length)) !== "") {
@@ -66364,7 +66364,7 @@ var require_sprintf = __commonJS({
66364
66364
  } else {
66365
66365
  throw new SyntaxError("[sprintf] failed to parse named argument key");
66366
66366
  }
66367
- match[2] = field_list;
66367
+ match2[2] = field_list;
66368
66368
  } else {
66369
66369
  arg_names |= 2;
66370
66370
  }
@@ -66373,21 +66373,21 @@ var require_sprintf = __commonJS({
66373
66373
  }
66374
66374
  parse_tree.push(
66375
66375
  {
66376
- placeholder: match[0],
66377
- param_no: match[1],
66378
- keys: match[2],
66379
- sign: match[3],
66380
- pad_char: match[4],
66381
- align: match[5],
66382
- width: match[6],
66383
- precision: match[7],
66384
- type: match[8]
66376
+ placeholder: match2[0],
66377
+ param_no: match2[1],
66378
+ keys: match2[2],
66379
+ sign: match2[3],
66380
+ pad_char: match2[4],
66381
+ align: match2[5],
66382
+ width: match2[6],
66383
+ precision: match2[7],
66384
+ type: match2[8]
66385
66385
  }
66386
66386
  );
66387
66387
  } else {
66388
66388
  throw new SyntaxError("[sprintf] unexpected placeholder");
66389
66389
  }
66390
- _fmt = _fmt.substring(match[0].length);
66390
+ _fmt = _fmt.substring(match2[0].length);
66391
66391
  }
66392
66392
  return sprintf_cache[fmt] = parse_tree;
66393
66393
  }
@@ -84309,8 +84309,8 @@ var require_string_decoder = __commonJS({
84309
84309
  if (typeof nenc !== "string" && (Buffer3.isEncoding === isEncoding || !isEncoding(enc3))) throw new Error("Unknown encoding: " + enc3);
84310
84310
  return nenc || enc3;
84311
84311
  }
84312
- exports.StringDecoder = StringDecoder;
84313
- function StringDecoder(encoding) {
84312
+ exports.StringDecoder = StringDecoder2;
84313
+ function StringDecoder2(encoding) {
84314
84314
  this.encoding = normalizeEncoding(encoding);
84315
84315
  var nb;
84316
84316
  switch (this.encoding) {
@@ -84337,7 +84337,7 @@ var require_string_decoder = __commonJS({
84337
84337
  this.lastTotal = 0;
84338
84338
  this.lastChar = Buffer3.allocUnsafe(nb);
84339
84339
  }
84340
- StringDecoder.prototype.write = function(buf) {
84340
+ StringDecoder2.prototype.write = function(buf) {
84341
84341
  if (buf.length === 0) return "";
84342
84342
  var r;
84343
84343
  var i;
@@ -84352,9 +84352,9 @@ var require_string_decoder = __commonJS({
84352
84352
  if (i < buf.length) return r ? r + this.text(buf, i) : this.text(buf, i);
84353
84353
  return r || "";
84354
84354
  };
84355
- StringDecoder.prototype.end = utf8End;
84356
- StringDecoder.prototype.text = utf8Text;
84357
- StringDecoder.prototype.fillLast = function(buf) {
84355
+ StringDecoder2.prototype.end = utf8End;
84356
+ StringDecoder2.prototype.text = utf8Text;
84357
+ StringDecoder2.prototype.fillLast = function(buf) {
84358
84358
  if (this.lastNeed <= buf.length) {
84359
84359
  buf.copy(this.lastChar, this.lastTotal - this.lastNeed, 0, this.lastNeed);
84360
84360
  return this.lastChar.toString(this.encoding, 0, this.lastTotal);
@@ -84631,7 +84631,7 @@ var require_readable = __commonJS({
84631
84631
  } = require_errors5();
84632
84632
  var { validateObject } = require_validators();
84633
84633
  var kPaused = Symbol2("kPaused");
84634
- var { StringDecoder } = require_string_decoder();
84634
+ var { StringDecoder: StringDecoder2 } = require_string_decoder();
84635
84635
  var from = require_from();
84636
84636
  ObjectSetPrototypeOf(Readable.prototype, Stream.prototype);
84637
84637
  ObjectSetPrototypeOf(Readable, Stream);
@@ -84725,7 +84725,7 @@ var require_readable = __commonJS({
84725
84725
  this.decoder = null;
84726
84726
  this.encoding = null;
84727
84727
  if (options2 && options2.encoding) {
84728
- this.decoder = new StringDecoder(options2.encoding);
84728
+ this.decoder = new StringDecoder2(options2.encoding);
84729
84729
  this.encoding = options2.encoding;
84730
84730
  }
84731
84731
  }
@@ -84844,7 +84844,7 @@ var require_readable = __commonJS({
84844
84844
  return state[kPaused] === true || state.flowing === false;
84845
84845
  };
84846
84846
  Readable.prototype.setEncoding = function(enc3) {
84847
- const decoder = new StringDecoder(enc3);
84847
+ const decoder = new StringDecoder2(enc3);
84848
84848
  this._readableState.decoder = decoder;
84849
84849
  this._readableState.encoding = this._readableState.decoder.encoding;
84850
84850
  const buffer = this._readableState.buffer;
@@ -85568,8 +85568,8 @@ var require_writable = __commonJS({
85568
85568
  Symbol: Symbol2,
85569
85569
  SymbolHasInstance
85570
85570
  } = require_primordials();
85571
- module.exports = Writable2;
85572
- Writable2.WritableState = WritableState;
85571
+ module.exports = Writable;
85572
+ Writable.WritableState = WritableState;
85573
85573
  var { EventEmitter: EE } = __require("events");
85574
85574
  var Stream = require_legacy().Stream;
85575
85575
  var { Buffer: Buffer3 } = __require("buffer");
@@ -85588,8 +85588,8 @@ var require_writable = __commonJS({
85588
85588
  ERR_UNKNOWN_ENCODING
85589
85589
  } = require_errors5().codes;
85590
85590
  var { errorOrDestroy } = destroyImpl;
85591
- ObjectSetPrototypeOf(Writable2.prototype, Stream.prototype);
85592
- ObjectSetPrototypeOf(Writable2, Stream);
85591
+ ObjectSetPrototypeOf(Writable.prototype, Stream.prototype);
85592
+ ObjectSetPrototypeOf(Writable, Stream);
85593
85593
  function nop() {
85594
85594
  }
85595
85595
  var kOnFinished = Symbol2("kOnFinished");
@@ -85643,9 +85643,9 @@ var require_writable = __commonJS({
85643
85643
  return this.buffered.length - this.bufferedIndex;
85644
85644
  }
85645
85645
  });
85646
- function Writable2(options2) {
85646
+ function Writable(options2) {
85647
85647
  const isDuplex = this instanceof require_duplex();
85648
- if (!isDuplex && !FunctionPrototypeSymbolHasInstance(Writable2, this)) return new Writable2(options2);
85648
+ if (!isDuplex && !FunctionPrototypeSymbolHasInstance(Writable, this)) return new Writable(options2);
85649
85649
  this._writableState = new WritableState(options2, this, isDuplex);
85650
85650
  if (options2) {
85651
85651
  if (typeof options2.write === "function") this._write = options2.write;
@@ -85664,15 +85664,15 @@ var require_writable = __commonJS({
85664
85664
  finishMaybe(this, state);
85665
85665
  });
85666
85666
  }
85667
- ObjectDefineProperty(Writable2, SymbolHasInstance, {
85667
+ ObjectDefineProperty(Writable, SymbolHasInstance, {
85668
85668
  __proto__: null,
85669
85669
  value: function(object3) {
85670
85670
  if (FunctionPrototypeSymbolHasInstance(this, object3)) return true;
85671
- if (this !== Writable2) return false;
85671
+ if (this !== Writable) return false;
85672
85672
  return object3 && object3._writableState instanceof WritableState;
85673
85673
  }
85674
85674
  });
85675
- Writable2.prototype.pipe = function() {
85675
+ Writable.prototype.pipe = function() {
85676
85676
  errorOrDestroy(this, new ERR_STREAM_CANNOT_PIPE());
85677
85677
  };
85678
85678
  function _write(stream, chunk, encoding, cb) {
@@ -85716,20 +85716,20 @@ var require_writable = __commonJS({
85716
85716
  state.pendingcb++;
85717
85717
  return writeOrBuffer(stream, state, chunk, encoding, cb);
85718
85718
  }
85719
- Writable2.prototype.write = function(chunk, encoding, cb) {
85719
+ Writable.prototype.write = function(chunk, encoding, cb) {
85720
85720
  return _write(this, chunk, encoding, cb) === true;
85721
85721
  };
85722
- Writable2.prototype.cork = function() {
85722
+ Writable.prototype.cork = function() {
85723
85723
  this._writableState.corked++;
85724
85724
  };
85725
- Writable2.prototype.uncork = function() {
85725
+ Writable.prototype.uncork = function() {
85726
85726
  const state = this._writableState;
85727
85727
  if (state.corked) {
85728
85728
  state.corked--;
85729
85729
  if (!state.writing) clearBuffer(this, state);
85730
85730
  }
85731
85731
  };
85732
- Writable2.prototype.setDefaultEncoding = function setDefaultEncoding(encoding) {
85732
+ Writable.prototype.setDefaultEncoding = function setDefaultEncoding(encoding) {
85733
85733
  if (typeof encoding === "string") encoding = StringPrototypeToLowerCase(encoding);
85734
85734
  if (!Buffer3.isEncoding(encoding)) throw new ERR_UNKNOWN_ENCODING(encoding);
85735
85735
  this._writableState.defaultEncoding = encoding;
@@ -85905,7 +85905,7 @@ var require_writable = __commonJS({
85905
85905
  }
85906
85906
  state.bufferProcessing = false;
85907
85907
  }
85908
- Writable2.prototype._write = function(chunk, encoding, cb) {
85908
+ Writable.prototype._write = function(chunk, encoding, cb) {
85909
85909
  if (this._writev) {
85910
85910
  this._writev(
85911
85911
  [
@@ -85920,8 +85920,8 @@ var require_writable = __commonJS({
85920
85920
  throw new ERR_METHOD_NOT_IMPLEMENTED("_write()");
85921
85921
  }
85922
85922
  };
85923
- Writable2.prototype._writev = null;
85924
- Writable2.prototype.end = function(chunk, encoding, cb) {
85923
+ Writable.prototype._writev = null;
85924
+ Writable.prototype.end = function(chunk, encoding, cb) {
85925
85925
  const state = this._writableState;
85926
85926
  if (typeof chunk === "function") {
85927
85927
  cb = chunk;
@@ -86048,7 +86048,7 @@ var require_writable = __commonJS({
86048
86048
  }
86049
86049
  }
86050
86050
  }
86051
- ObjectDefineProperties(Writable2.prototype, {
86051
+ ObjectDefineProperties(Writable.prototype, {
86052
86052
  closed: {
86053
86053
  __proto__: null,
86054
86054
  get() {
@@ -86144,7 +86144,7 @@ var require_writable = __commonJS({
86144
86144
  }
86145
86145
  });
86146
86146
  var destroy = destroyImpl.destroy;
86147
- Writable2.prototype.destroy = function(err, cb) {
86147
+ Writable.prototype.destroy = function(err, cb) {
86148
86148
  const state = this._writableState;
86149
86149
  if (!state.destroyed && (state.bufferedIndex < state.buffered.length || state[kOnFinished].length)) {
86150
86150
  process4.nextTick(errorBuffer, state);
@@ -86152,11 +86152,11 @@ var require_writable = __commonJS({
86152
86152
  destroy.call(this, err, cb);
86153
86153
  return this;
86154
86154
  };
86155
- Writable2.prototype._undestroy = destroyImpl.undestroy;
86156
- Writable2.prototype._destroy = function(err, cb) {
86155
+ Writable.prototype._undestroy = destroyImpl.undestroy;
86156
+ Writable.prototype._destroy = function(err, cb) {
86157
86157
  cb(err);
86158
86158
  };
86159
- Writable2.prototype[EE.captureRejectionSymbol] = function(err) {
86159
+ Writable.prototype[EE.captureRejectionSymbol] = function(err) {
86160
86160
  this.destroy(err);
86161
86161
  };
86162
86162
  var webStreamsAdapters;
@@ -86164,10 +86164,10 @@ var require_writable = __commonJS({
86164
86164
  if (webStreamsAdapters === void 0) webStreamsAdapters = {};
86165
86165
  return webStreamsAdapters;
86166
86166
  }
86167
- Writable2.fromWeb = function(writableStream, options2) {
86167
+ Writable.fromWeb = function(writableStream, options2) {
86168
86168
  return lazyWebStreams().newStreamWritableFromWritableStream(writableStream, options2);
86169
86169
  };
86170
- Writable2.toWeb = function(streamWritable) {
86170
+ Writable.toWeb = function(streamWritable) {
86171
86171
  return lazyWebStreams().newWritableStreamFromStreamWritable(streamWritable);
86172
86172
  };
86173
86173
  }
@@ -86198,7 +86198,7 @@ var require_duplexify = __commonJS({
86198
86198
  var { destroyer } = require_destroy();
86199
86199
  var Duplex = require_duplex();
86200
86200
  var Readable = require_readable();
86201
- var Writable2 = require_writable();
86201
+ var Writable = require_writable();
86202
86202
  var { createDeferredPromise } = require_util4();
86203
86203
  var from = require_from();
86204
86204
  var Blob = globalThis.Blob || bufferModule.Blob;
@@ -86252,7 +86252,7 @@ var require_duplexify = __commonJS({
86252
86252
  }
86253
86253
  if (isWritableStream(body)) {
86254
86254
  return _duplexify({
86255
- writable: Writable2.fromWeb(body)
86255
+ writable: Writable.fromWeb(body)
86256
86256
  });
86257
86257
  }
86258
86258
  if (typeof body === "function") {
@@ -86533,20 +86533,20 @@ var require_duplex = __commonJS({
86533
86533
  } = require_primordials();
86534
86534
  module.exports = Duplex;
86535
86535
  var Readable = require_readable();
86536
- var Writable2 = require_writable();
86536
+ var Writable = require_writable();
86537
86537
  ObjectSetPrototypeOf(Duplex.prototype, Readable.prototype);
86538
86538
  ObjectSetPrototypeOf(Duplex, Readable);
86539
86539
  {
86540
- const keys2 = ObjectKeys(Writable2.prototype);
86540
+ const keys2 = ObjectKeys(Writable.prototype);
86541
86541
  for (let i = 0; i < keys2.length; i++) {
86542
86542
  const method = keys2[i];
86543
- if (!Duplex.prototype[method]) Duplex.prototype[method] = Writable2.prototype[method];
86543
+ if (!Duplex.prototype[method]) Duplex.prototype[method] = Writable.prototype[method];
86544
86544
  }
86545
86545
  }
86546
86546
  function Duplex(options2) {
86547
86547
  if (!(this instanceof Duplex)) return new Duplex(options2);
86548
86548
  Readable.call(this, options2);
86549
- Writable2.call(this, options2);
86549
+ Writable.call(this, options2);
86550
86550
  if (options2) {
86551
86551
  this.allowHalfOpen = options2.allowHalfOpen !== false;
86552
86552
  if (options2.readable === false) {
@@ -86567,39 +86567,39 @@ var require_duplex = __commonJS({
86567
86567
  ObjectDefineProperties(Duplex.prototype, {
86568
86568
  writable: {
86569
86569
  __proto__: null,
86570
- ...ObjectGetOwnPropertyDescriptor(Writable2.prototype, "writable")
86570
+ ...ObjectGetOwnPropertyDescriptor(Writable.prototype, "writable")
86571
86571
  },
86572
86572
  writableHighWaterMark: {
86573
86573
  __proto__: null,
86574
- ...ObjectGetOwnPropertyDescriptor(Writable2.prototype, "writableHighWaterMark")
86574
+ ...ObjectGetOwnPropertyDescriptor(Writable.prototype, "writableHighWaterMark")
86575
86575
  },
86576
86576
  writableObjectMode: {
86577
86577
  __proto__: null,
86578
- ...ObjectGetOwnPropertyDescriptor(Writable2.prototype, "writableObjectMode")
86578
+ ...ObjectGetOwnPropertyDescriptor(Writable.prototype, "writableObjectMode")
86579
86579
  },
86580
86580
  writableBuffer: {
86581
86581
  __proto__: null,
86582
- ...ObjectGetOwnPropertyDescriptor(Writable2.prototype, "writableBuffer")
86582
+ ...ObjectGetOwnPropertyDescriptor(Writable.prototype, "writableBuffer")
86583
86583
  },
86584
86584
  writableLength: {
86585
86585
  __proto__: null,
86586
- ...ObjectGetOwnPropertyDescriptor(Writable2.prototype, "writableLength")
86586
+ ...ObjectGetOwnPropertyDescriptor(Writable.prototype, "writableLength")
86587
86587
  },
86588
86588
  writableFinished: {
86589
86589
  __proto__: null,
86590
- ...ObjectGetOwnPropertyDescriptor(Writable2.prototype, "writableFinished")
86590
+ ...ObjectGetOwnPropertyDescriptor(Writable.prototype, "writableFinished")
86591
86591
  },
86592
86592
  writableCorked: {
86593
86593
  __proto__: null,
86594
- ...ObjectGetOwnPropertyDescriptor(Writable2.prototype, "writableCorked")
86594
+ ...ObjectGetOwnPropertyDescriptor(Writable.prototype, "writableCorked")
86595
86595
  },
86596
86596
  writableEnded: {
86597
86597
  __proto__: null,
86598
- ...ObjectGetOwnPropertyDescriptor(Writable2.prototype, "writableEnded")
86598
+ ...ObjectGetOwnPropertyDescriptor(Writable.prototype, "writableEnded")
86599
86599
  },
86600
86600
  writableNeedDrain: {
86601
86601
  __proto__: null,
86602
- ...ObjectGetOwnPropertyDescriptor(Writable2.prototype, "writableNeedDrain")
86602
+ ...ObjectGetOwnPropertyDescriptor(Writable.prototype, "writableNeedDrain")
86603
86603
  },
86604
86604
  destroyed: {
86605
86605
  __proto__: null,
@@ -106172,7 +106172,7 @@ async function scan(input4, filters, v, run3 = {}) {
106172
106172
  let py;
106173
106173
  let pending;
106174
106174
  let grepHit = false;
106175
- const match = (number4, text4, rest, level2, pyTrace) => {
106175
+ const match2 = (number4, text4, rest, level2, pyTrace) => {
106176
106176
  lines[level2]++;
106177
106177
  anchor2 = void 0;
106178
106178
  const { since: since2, grep } = filters;
@@ -106239,7 +106239,7 @@ async function scan(input4, filters, v, run3 = {}) {
106239
106239
  const block2 = py;
106240
106240
  py = void 0;
106241
106241
  if (rest.trim() !== "") {
106242
- match(line.number, line.text, rest, "error", block2);
106242
+ match2(line.number, line.text, rest, "error", block2);
106243
106243
  continue;
106244
106244
  }
106245
106245
  out.unjoinedFrames += block2.end - block2.start + 1;
@@ -106278,7 +106278,7 @@ async function scan(input4, filters, v, run3 = {}) {
106278
106278
  if (anchor2 && (anchor2.inTrace || level2 !== void 0 || rest.trim() === "" || ++anchor2.gap > MAX_GAP)) anchor2 = void 0;
106279
106279
  if (level2 === void 0) lines.unclassified++;
106280
106280
  else if (level2 === "other") lines.other++;
106281
- else match(line.number, line.text, rest, level2);
106281
+ else match2(line.number, line.text, rest, level2);
106282
106282
  }
106283
106283
  if (pending) out.filtered++;
106284
106284
  if (py) out.unjoinedFrames += py.end - py.start + 1;
@@ -109646,8 +109646,8 @@ function instant(value2) {
109646
109646
  function day(value2) {
109647
109647
  if (value2 === null || value2 === void 0 || value2 === "") return null;
109648
109648
  if (typeof value2 !== "string") return void 0;
109649
- const match = /^(\d{4}-\d{2}-\d{2})/.exec(value2);
109650
- return match ? match[1] : void 0;
109649
+ const match2 = /^(\d{4}-\d{2}-\d{2})/.exec(value2);
109650
+ return match2 ? match2[1] : void 0;
109651
109651
  }
109652
109652
  function typeOf4(name3, extra = {}) {
109653
109653
  if (name3 === null) return "OTHER";
@@ -109747,8 +109747,8 @@ function workItemsOf(data) {
109747
109747
  function adoPerson(value2) {
109748
109748
  if (isRecord5(value2)) return person2(value2.uniqueName ?? value2.id, value2.displayName, typeof value2.uniqueName === "string" && value2.uniqueName.includes("@") ? value2.uniqueName : null);
109749
109749
  if (typeof value2 === "string") {
109750
- const match = /^(.*?)\s*<([^>]+)>$/.exec(value2);
109751
- return match ? person2(match[2], match[1], match[2].includes("@") ? match[2] : null) : person2(value2, value2, null);
109750
+ const match2 = /^(.*?)\s*<([^>]+)>$/.exec(value2);
109751
+ return match2 ? person2(match2[2], match2[1], match2[2].includes("@") ? match2[2] : null) : person2(value2, value2, null);
109752
109752
  }
109753
109753
  return null;
109754
109754
  }
@@ -110088,7 +110088,7 @@ var init_change = __esm({
110088
110088
  notIncluded = (doc, list7) => doc.command.endsWith(" pr list") ? `${doc.command} doesn't return ${list7}: map ${doc.area} pr get --include ${list7} for each pull request as well` : `the input wasn't read with --include ${list7}: map ${doc.area} pr get --include ${list7}`;
110089
110089
  NAME3 = /^[a-z0-9]+(-[a-z0-9]+)*$/;
110090
110090
  escape3 = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
110091
- keyOf2 = (pattern, match, n) => pattern.text.endsWith("#{n}") && !pattern.text.includes("/") ? n : match;
110091
+ keyOf2 = (pattern, match2, n) => pattern.text.endsWith("#{n}") && !pattern.text.includes("/") ? n : match2;
110092
110092
  withoutCode = (s) => s.replace(/```[\s\S]*?```/g, " ").replace(/`[^`\n]*`/g, " ");
110093
110093
  HASH_NUMBER = /(?<![\w/#-])#(\d+)\b/g;
110094
110094
  AGENT_BRANCH_PREFIXES = ["claude/", "copilot/", "codex/"];
@@ -112289,6 +112289,9 @@ async function similarOwi(ctx, input4) {
112289
112289
  ctx.warn({ code: "OWI_SIMILAR_TITLE_ONLY", message: `${found.titleOnly.length} of ${found.items} items have no body, so they were scored on their titles alone: ${some(found.titleOnly)}. Where the tracker holds a body for them, map them from a command that returns it (jira issue get, or jira issue search with description in --fields).` });
112290
112290
  }
112291
112291
  if (found.cutBodies.length) ctx.warn({ code: "OWI_SIMILAR_BODY_CUT", message: `${found.cutBodies.length} item${found.cutBodies.length > 1 ? "s have bodies" : " has a body"} longer than the 5,000 terms scored; the rest was left out: ${some(found.cutBodies)}.` });
112292
+ if (result.mode === "query" && result.count === 0) {
112293
+ ctx.warn({ code: "OWI_SIMILAR_NO_MATCH", message: `No item scores ${threshold} or more against the query, so there is no likely ticket for it among these ${found.items}. Suggest creating one; don't lower --threshold to force a match.` });
112294
+ }
112292
112295
  if (threshold <= MAX_BOOST) ctx.warn({ code: "OWI_SIMILAR_LOW_THRESHOLD", message: `A threshold of ${threshold} lets boosts alone (shared labels, the same parent, a link, up to ${MAX_BOOST}) count as a match, with no shared words. Raise --threshold above ${MAX_BOOST} for likely duplicates.` });
112293
112296
  const v = new Verifier(ctx.warn);
112294
112297
  const scored = [...result.matches.map((m2) => ({ at: m2.id, score: m2.score, why: m2.why })), ...result.pairs.map((p) => ({ at: `${p.a.id} and ${p.b.id}`, score: p.score, why: p.why }))];
@@ -123020,8 +123023,8 @@ var error43 = () => {
123020
123023
  case "not_multiple_of":
123021
123024
  return `N\xFAmero inv\xE1lido: deve ser m\xFAltiplo de ${issue2.divisor}`;
123022
123025
  case "unrecognized_keys": {
123023
- const plural3 = issue2.keys.length > 1 ? "s" : "";
123024
- return `Chave${plural3} inv\xE1lida${plural3}: ${joinValues(issue2.keys, ", ")}`;
123026
+ const plural4 = issue2.keys.length > 1 ? "s" : "";
123027
+ return `Chave${plural4} inv\xE1lida${plural4}: ${joinValues(issue2.keys, ", ")}`;
123025
123028
  }
123026
123029
  case "invalid_key":
123027
123030
  return `Entrada inv\xE1lida n${translateOriginWithArticle(issue2.origin, "definite")}`;
@@ -123165,8 +123168,8 @@ var error44 = () => {
123165
123168
  case "not_multiple_of":
123166
123169
  return `N\xFAmero inv\xE1lido: deve ser m\xFAltiplo de ${issue2.divisor}`;
123167
123170
  case "unrecognized_keys": {
123168
- const plural3 = issue2.keys.length > 1 ? "s" : "";
123169
- return `Chave${plural3} inv\xE1lida${plural3}: ${joinValues(issue2.keys, ", ")}`;
123171
+ const plural4 = issue2.keys.length > 1 ? "s" : "";
123172
+ return `Chave${plural4} inv\xE1lida${plural4}: ${joinValues(issue2.keys, ", ")}`;
123170
123173
  }
123171
123174
  case "invalid_key":
123172
123175
  return `Entrada inv\xE1lida n${translateOriginWithArticle(issue2.origin, "definite")}`;
@@ -134832,10 +134835,10 @@ function findSecrets(text4) {
134832
134835
  found.sort((a, b) => a.index - b.index || b.length - a.length);
134833
134836
  const kept = [];
134834
134837
  let furthest = -1;
134835
- for (const match of found) {
134836
- const end2 = match.index + match.length;
134838
+ for (const match2 of found) {
134839
+ const end2 = match2.index + match2.length;
134837
134840
  if (end2 <= furthest) continue;
134838
- kept.push(match);
134841
+ kept.push(match2);
134839
134842
  furthest = end2;
134840
134843
  }
134841
134844
  return kept;
@@ -135338,9 +135341,9 @@ function connectionEnvName(connection5, key6) {
135338
135341
  function parseEnvName(name3, knownAreas) {
135339
135342
  if (!name3.startsWith("TOIL_") || RESERVED_ENV.some((re) => re.test(name3))) return void 0;
135340
135343
  const rest = name3.slice(5);
135341
- const match = knownAreas.map((area31) => ({ area: area31, prefix: `${envForm(area31)}_` })).filter((p) => rest.startsWith(p.prefix) && rest.length > p.prefix.length).sort((a, b) => b.prefix.length - a.prefix.length)[0];
135342
- if (!match) return void 0;
135343
- return { area: match.area, key: camel(rest.slice(match.prefix.length)) };
135344
+ const match2 = knownAreas.map((area31) => ({ area: area31, prefix: `${envForm(area31)}_` })).filter((p) => rest.startsWith(p.prefix) && rest.length > p.prefix.length).sort((a, b) => b.prefix.length - a.prefix.length)[0];
135345
+ if (!match2) return void 0;
135346
+ return { area: match2.area, key: camel(rest.slice(match2.prefix.length)) };
135344
135347
  }
135345
135348
  function fromEnv(env, knownAreas = []) {
135346
135349
  const out = {};
@@ -135658,43 +135661,134 @@ async function storeVerified(store, ref2, secret, signal) {
135658
135661
  // src/core/prompt.ts
135659
135662
  init_errors();
135660
135663
  import { createInterface } from "node:readline/promises";
135661
- import { Writable } from "node:stream";
135662
- function terminalPrompter(input4, output3) {
135663
- let muted3 = false;
135664
- const echo = new Writable({
135665
- write(chunk, _encoding, done) {
135666
- if (!muted3) output3.write(chunk);
135667
- done();
135664
+ import { StringDecoder } from "node:string_decoder";
135665
+ var HiddenLine = class {
135666
+ chars = [];
135667
+ escape = "";
135668
+ pasting = false;
135669
+ get count() {
135670
+ return this.chars.length;
135671
+ }
135672
+ get value() {
135673
+ return this.chars.join("");
135674
+ }
135675
+ /** Feeds one chunk as it arrived. `enter` and `cancel` end the line; anything after them in the chunk is dropped. */
135676
+ feed(chunk) {
135677
+ const pieces = this.split(chunk);
135678
+ const endsLine = /^[^\r\n]*[\r\n]+$/.test(pieces.filter((p) => !p.pasted && !EDITS.has(p.c)).map((p) => p.c).join(""));
135679
+ for (const { c, pasted } of pieces) {
135680
+ if (pasted) {
135681
+ if (isText(c) || c === " " || c === "\r" || c === "\n") this.chars.push(c);
135682
+ } else if (c === "") return "cancel";
135683
+ else if (c === "\r" || c === "\n") {
135684
+ if (endsLine) return "enter";
135685
+ this.chars.push(c);
135686
+ } else if (c === "\x7F" || c === "\b") this.chars.pop();
135687
+ else if (c === "") this.chars = [];
135688
+ else if (c === " " || isText(c)) this.chars.push(c);
135668
135689
  }
135669
- });
135670
- const read = async (question, secret) => {
135671
- const rl = createInterface({ input: input4, output: echo, terminal: true });
135690
+ return null;
135691
+ }
135692
+ /** The chunk's characters with escape sequences taken out, each marked by whether a bracketed paste carried it. */
135693
+ split(chunk) {
135694
+ const out = [];
135695
+ for (const c of chunk) {
135696
+ if (this.escape === "\x1B" && c !== "[" && c !== "O") this.escape = "";
135697
+ if (this.escape === "" && c !== "\x1B") {
135698
+ out.push({ c, pasted: this.pasting });
135699
+ continue;
135700
+ }
135701
+ this.escape += c;
135702
+ const e = this.escape;
135703
+ if (e.length >= 2 && (e[1] === "[" ? e.length > 2 && /[@-~]/.test(c) : e.length === 3)) {
135704
+ if (e === "\x1B[200~") this.pasting = true;
135705
+ else if (e === "\x1B[201~") this.pasting = false;
135706
+ this.escape = "";
135707
+ }
135708
+ }
135709
+ return out;
135710
+ }
135711
+ };
135712
+ var EDITS = /* @__PURE__ */ new Set(["\x7F", "\b", ""]);
135713
+ var isText = (c) => c >= " " && c !== "\x7F" && !(c >= "\x80" && c <= "\x9F");
135714
+ var BULLET = "\u2022";
135715
+ function terminalPrompter(input4, output3) {
135716
+ const ask = async (question) => {
135717
+ const rl = createInterface({ input: input4, output: output3, terminal: true });
135672
135718
  const cancelled2 = new Promise(
135673
135719
  (_2, reject) => (
135674
135720
  // In raw mode Ctrl+C reaches readline, not the process.
135675
- rl.once("SIGINT", () => reject(new ToilError("CANCELLED", "Setup was cancelled. Nothing was saved.")))
135721
+ rl.once("SIGINT", () => reject(cancel()))
135676
135722
  )
135677
135723
  );
135678
135724
  try {
135679
- const cut2 = secret ? -1 : question.lastIndexOf("\n");
135725
+ const cut2 = question.lastIndexOf("\n");
135680
135726
  if (cut2 >= 0) output3.write(question.slice(0, cut2 + 1));
135681
- if (secret) output3.write(question);
135682
- muted3 = secret;
135683
- return (await Promise.race([rl.question(secret ? "" : question.slice(cut2 + 1)), cancelled2])).trim();
135727
+ return (await Promise.race([rl.question(question.slice(cut2 + 1)), cancelled2])).trim();
135684
135728
  } finally {
135685
- muted3 = false;
135686
- if (secret) output3.write("\n");
135687
135729
  rl.close();
135688
135730
  }
135689
135731
  };
135732
+ const askHidden = (question) => new Promise((resolve10, reject) => {
135733
+ const tty = input4;
135734
+ const wasRaw = tty.isRaw === true;
135735
+ tty.setRawMode?.(true);
135736
+ const columns = () => {
135737
+ const c = output3.columns;
135738
+ return typeof c === "number" && c > 0 ? c : 80;
135739
+ };
135740
+ const lastLine = question.slice(question.lastIndexOf("\n") + 1);
135741
+ const offset = [...lastLine].length;
135742
+ const line = new HiddenLine();
135743
+ const decoder = new StringDecoder("utf8");
135744
+ let drawn = 0;
135745
+ const draw3 = () => {
135746
+ const n = line.count;
135747
+ if (n >= drawn) output3.write(BULLET.repeat(n - drawn));
135748
+ else {
135749
+ const rows = Math.max(0, Math.floor((offset + drawn - 1) / columns()));
135750
+ output3.write(`${rows ? `\x1B[${rows}A` : ""}\r\x1B[J${lastLine}${BULLET.repeat(n)}`);
135751
+ }
135752
+ drawn = n;
135753
+ };
135754
+ const pasteOff = () => output3.write("\x1B[?2004l");
135755
+ const finish5 = (error62) => {
135756
+ input4.off("data", onData);
135757
+ input4.off("end", onEnd);
135758
+ process.off("exit", pasteOff);
135759
+ output3.write("\x1B[?2004l\r\n");
135760
+ tty.setRawMode?.(wasRaw);
135761
+ input4.pause();
135762
+ if (error62) reject(error62);
135763
+ else resolve10(line.value);
135764
+ };
135765
+ const onData = (chunk) => {
135766
+ const result = line.feed(typeof chunk === "string" ? chunk : decoder.write(chunk));
135767
+ draw3();
135768
+ if (result === "enter") finish5(null);
135769
+ else if (result === "cancel") finish5(cancel());
135770
+ };
135771
+ const onEnd = () => finish5(cancel());
135772
+ output3.write(`${question}\x1B[?2004h`);
135773
+ process.once("exit", pasteOff);
135774
+ input4.on("data", onData);
135775
+ input4.on("end", onEnd);
135776
+ input4.resume();
135777
+ });
135690
135778
  return {
135691
135779
  ask: async (question, fallback) => {
135692
- const answer2 = await read(`${question}${fallback ? ` [${fallback}]` : ""}: `, false);
135780
+ const answer2 = await ask(`${question}${fallback ? ` [${fallback}]` : ""}: `);
135693
135781
  return answer2 === "" ? fallback ?? "" : answer2;
135694
135782
  },
135695
- askSecret: (question) => read(`${question} (input hidden): `, true)
135783
+ askSecret: (question) => askHidden(`${question} (input hidden): `),
135784
+ note: (line) => output3.write(`${line}
135785
+ `),
135786
+ canAskAgain: true
135696
135787
  };
135697
135788
  }
135789
+ function cancel() {
135790
+ return new ToilError("CANCELLED", "Setup was cancelled. Nothing was saved.");
135791
+ }
135698
135792
 
135699
135793
  // node_modules/@modelcontextprotocol/sdk/dist/esm/server/zod-compat.js
135700
135794
  function isZ4Schema(s) {
@@ -136356,7 +136450,7 @@ var Protocol = class {
136356
136450
  }
136357
136451
  };
136358
136452
  }
136359
- const cancel = (reason) => {
136453
+ const cancel2 = (reason) => {
136360
136454
  this._responseHandlers.delete(messageId);
136361
136455
  this._progressHandlers.delete(messageId);
136362
136456
  this._cleanupTimeout(messageId);
@@ -136390,10 +136484,10 @@ var Protocol = class {
136390
136484
  }
136391
136485
  });
136392
136486
  options2?.signal?.addEventListener("abort", () => {
136393
- cancel(options2?.signal?.reason);
136487
+ cancel2(options2?.signal?.reason);
136394
136488
  });
136395
136489
  const timeout = options2?.timeout ?? DEFAULT_REQUEST_TIMEOUT_MSEC;
136396
- const timeoutHandler = () => cancel(McpError.fromError(ErrorCode.RequestTimeout, "Request timed out", { timeout }));
136490
+ const timeoutHandler = () => cancel2(McpError.fromError(ErrorCode.RequestTimeout, "Request timed out", { timeout }));
136397
136491
  this._setupTimeout(messageId, timeout, options2?.maxTotalTimeout, timeoutHandler, options2?.resetTimeoutOnProgress ?? false);
136398
136492
  const relatedTaskId = relatedTask?.taskId;
136399
136493
  if (relatedTaskId) {
@@ -137458,6 +137552,15 @@ function defineArea(spec) {
137458
137552
  for (const key6 of Object.keys(spec.examples ?? {})) {
137459
137553
  if (!(key6 in spec.connection.shape)) throw new Error(`Area ${spec.name}: example "${key6}" isn't a connection key.`);
137460
137554
  }
137555
+ for (const [host, url2] of Object.entries(spec.siteApis ?? {})) {
137556
+ let ok2;
137557
+ try {
137558
+ ok2 = host === host.toLowerCase() && !host.includes(":") && new URL(url2).protocol === "https:";
137559
+ } catch {
137560
+ ok2 = false;
137561
+ }
137562
+ if (!ok2) throw new Error(`Area ${spec.name}: siteApis maps a lowercase host with no port to an https base URL; "${host}" to "${url2}" isn't that.`);
137563
+ }
137461
137564
  for (const key6 of Object.keys(spec.removed ?? {})) {
137462
137565
  if (key6 in spec.connection.shape || key6 in (spec.renamed ?? {})) throw new Error(`Area ${spec.name}: removed key "${key6}" is still a connection key or a renamed one.`);
137463
137566
  }
@@ -138478,9 +138581,9 @@ var looksLikeGitDir = (dir) => existsSync4(join4(dir, "HEAD"));
138478
138581
  function gitDirOf(dotGit, guard) {
138479
138582
  if (isDir(dotGit)) return looksLikeGitDir(dotGit) ? dotGit : void 0;
138480
138583
  const text4 = readText(dotGit);
138481
- const match = text4?.match(/^gitdir: *(.+?)\s*$/m);
138482
- if (!match) return void 0;
138483
- const target2 = isAbsolute3(match[1]) ? match[1] : resolve3(dirname3(dotGit), match[1]);
138584
+ const match2 = text4?.match(/^gitdir: *(.+?)\s*$/m);
138585
+ if (!match2) return void 0;
138586
+ const target2 = isAbsolute3(match2[1]) ? match2[1] : resolve3(dirname3(dotGit), match2[1]);
138484
138587
  if (refusedGitRead(target2, guard.home, guard.protect)) return void 0;
138485
138588
  return looksLikeGitDir(target2) ? target2 : void 0;
138486
138589
  }
@@ -138503,8 +138606,8 @@ function findGitRepo(start2, guard = { home: homedir() }) {
138503
138606
  }
138504
138607
  function headRef(repo) {
138505
138608
  const head2 = readText(join4(repo.gitDir, "HEAD"))?.trim();
138506
- const match = head2?.match(/^ref: *(\S+)$/);
138507
- return match?.[1];
138609
+ const match2 = head2?.match(/^ref: *(\S+)$/);
138610
+ return match2?.[1];
138508
138611
  }
138509
138612
  function refExists(repo, ref2) {
138510
138613
  if (existsSync4(join4(repo.commonDir, ...ref2.split("/"))) || existsSync4(join4(repo.gitDir, ...ref2.split("/")))) return true;
@@ -138689,14 +138792,14 @@ function parseIgnore(text4, base, caseFold = false, onSkip) {
138689
138792
  if (line === "") continue;
138690
138793
  const basenameOnly = !line.includes("/");
138691
138794
  if (line.startsWith("/")) line = line.slice(1);
138692
- let match;
138795
+ let match2;
138693
138796
  try {
138694
- match = wildmatch(line, { pathname: true, caseFold });
138797
+ match2 = wildmatch(line, { pathname: true, caseFold });
138695
138798
  } catch (err) {
138696
138799
  onSkip?.({ line: n + 1, pattern: lines[n].trimEnd(), ...explain(err) });
138697
138800
  continue;
138698
138801
  }
138699
- rules.push({ base, match, negate, dirOnly, basenameOnly });
138802
+ rules.push({ base, match: match2, negate, dirOnly, basenameOnly });
138700
138803
  }
138701
138804
  return rules;
138702
138805
  }
@@ -140313,9 +140416,9 @@ var allowWriteField = {
140313
140416
 
140314
140417
  // src/skill-pages.generated.ts
140315
140418
  var skillFiles = {
140316
- "SKILL.md": "---\nname: toil\ndescription: Use toil, a structured-JSON CLI and MCP server, to read from and (when allowed) write to databases and the enterprise tools an organization runs, such as issue trackers, source hosts, wikis, CI, artifact repositories, scanners and observability. Use when a task needs data from one of those tools or a database, or mentions `toil` commands, `toil mcp`, a toil connection, or a TOIL_* environment variable.\n---\n\n# toil\n\ntoil is the token-efficient alternative to MCP: the same commands as a CLI, each\nreturning one compact envelope, with this skill read a file at a time rather than\nevery tool schema up front. Keep it lean: `--select` the fields you need, and\n`toil wait` rather than polling.\n\nIf `toil version` doesn't print an envelope, toil isn't installed yet: `install.md`,\nbeside this file, says how.\n\n## Every call\n\n- **Output.** Every command prints one JSON envelope on stdout: `{ ok, data, error,\n meta }`. Check `ok`; on failure, `error.code` says what kind of failure it was and\n `error.fix` what to do about it. `meta.warnings` lists what's worth knowing that\n isn't a failure, and `meta.page.nextCursor` the next page, when there is one.\n- **Two front doors, one command.** `toil <area> <command>` on the command line, or\n the MCP tool named after its path (`db_query`) from `toil mcp --areas <area>`, with\n identical inputs and output.\n- **Writes.** Reads are always allowed. A command that changes data needs\n `writes: true` on the connection, set by a person, and `--allow-write` on the call\n (`allowWrite: true` over MCP). Only make a write the user asked for. Four writes\n differ, each listed in `core.md` under **Writes**.\n- **Connections.** Environment variables always win over `~/.toil/config.json`.\n `--connection <name>` picks one when an area has several; `toil connections list`\n names them, never a secret. Setting one up is for a person: a bare `toil` in a\n terminal opens a menu for them.\n- **Files** a command reads or writes stay inside the workspace (`--workspace <dir>`,\n else the working directory).\n- **Feedback** to Imagile (`toil feedback`) only when the user asks, scrubbed of\n company data, shown to them in full with its disclaimer, and sent with `--consent`\n only after their yes to that exact report: `core.md`, **Feedback**.\n- **Less output.** `--select <expression>` keeps only the fields you name, and\n `toil wait --until <expression> -- <read>` repeats a read until it's true, instead\n of polling yourself. For any search or listing that may return more than a page,\n add `--summary-file <file>` (`summaryFile`): the full result goes to the file and\n you get a sample with stats; `--output-format toon` makes tables smaller still.\n\n## Where to look\n\nOpen only the file the task needs; each sits beside this one.\n\n| File | When |\n|------|------|\n| `core.md` | `--select`, big results (`--summary-file`, `--output-format toon`), `toil wait`, paging and progress, errors, writes and their exceptions, global flags, files, configuration, the raw `api` passthrough, dossiers, the audit log, calling toil from a program (`@imagile-dev/toil/api`), sending feedback, certificates and proxies |\n| `<area>.md` | One per area, named after it: `jira.md` for `toil jira \u2026`. Its frontmatter says what the area covers; the file gives the oldest version it supports, its credential, its configuration keys and every command |\n| `dossiers.md` | What a dossier is: one body of work mapped to your connections, its file, and how to build and share one |\n| `db.md` | Databases: `toil db \u2026` on every engine |\n| `util.md` | Local utilities with no connection or network: `toil util \u2026` |\n| `skills.md` | Skills marketplaces, and keeping this skill installed |\n| `mcp.md` | Running toil as an MCP server and registering it with an agent |\n| `install.md` | Installing toil, and this skill |\n\n`toil --help` lists the areas this install has.\n",
140317
- "ado-cloud.md": "---\narea: ado-cloud\ndescription: Work items, boards, backlogs, sprints, git repositories and pull requests on Azure DevOps Services (dev.azure.com)\n---\n\n# Azure DevOps Services (`ado-cloud`)\n\nWork items, a team's boards, backlogs and sprints, git repositories and pull requests\non **Azure DevOps Services** (`https://dev.azure.com/<organization>`, or the older\n`https://<organization>.visualstudio.com`), through its REST API with\n`api-version=7.1`. Built from Microsoft's REST API reference. The work item reads and\nthe team settings commands (sprints, backlogs, boards, work item type states) have\nbeen run against one live Scrum organization; the pull request commands have not.\nVerification level: `unit`.\n\nFor Azure DevOps Server (on-premises), use the `ado` area instead. The two are\nseparate areas so that neither one's fixes can change the other: a Services\nconnection is one organization, where a Server connection is a server holding\nseveral collections.\n\n**Supported versions:** The oldest Azure DevOps Services version toil supports hasn't been established.\nAzure DevOps Services is always current. toil sends `api-version=7.1`, the newest\nreleased version (7.2 is preview only), with `7.1-preview.1` for connection data and\n`7.1-preview.4` for work item comments, which exist only as previews.\n\n## Credential\n\nAn **organization-scoped personal access token**: in Azure DevOps, User settings \u2192\nPersonal access tokens \u2192 New Token, with **Organization** set to the one organization\nthis connection is for. Give it the scopes the commands you'll use need: Work Items\nand Code, Read (or Read & write for the write commands), plus Project and Team Read\nfor `project list`, `project get`, and the `sprint`, `backlog` and `board` commands\nwhen no team is given (toil reads the project for its default team). toil sends it as `Authorization: Basic base64(\":\" + token)`, with\nan empty user name.\n\n**Don't create a global token** (\"All accessible organizations\"). Microsoft is retiring\nglobal personal access tokens: every existing one stops working on **December 1,\n2026**. A connection is one organization, so an organization-scoped token is all it\nneeds. A `401` or `403` is `AUTH`, and its fix says to create an organization-scoped\ntoken and that global ones are being retired.\n\nThere is no OAuth, Microsoft Entra ID or service principal sign-in: those need a\nbrowser login or an app registration, and toil takes only a token you create once.\n\n## Configuration\n\n| Key | Env var | Required | Meaning |\n|-----|---------|----------|---------|\n| `baseUrl` | `TOIL_ADO_CLOUD_BASE_URL` | yes | Organization URL: `https://dev.azure.com/<organization>` (or `https://<organization>.visualstudio.com`) |\n| `pat` | `TOIL_ADO_CLOUD_PAT` | yes | Organization-scoped personal access token (a secret) |\n| `project` | `TOIL_ADO_CLOUD_PROJECT` | no | Default project, when `--project` isn't given |\n| `repo` | `TOIL_ADO_CLOUD_REPO` | no | Default git repository, when `--repo` isn't given |\n| `team` | `TOIL_ADO_CLOUD_TEAM` | no | Default team for the `sprint`, `backlog` and `board` commands, when `--team` isn't given (else the project's default team) |\n| `fieldAliases` | `TOIL_ADO_CLOUD_FIELD_ALIASES` | no | Work item field aliases as a JSON object, friendly name to reference name, e.g. `{\"effortdays\": \"MyOrg.EffortDays\"}` |\n| `writes` | `TOIL_ADO_CLOUD_WRITES` | no | `true` lets write commands run (with `--allow-write`) |\n\nA `baseUrl` that doesn't name exactly one organization is refused with\n`CONFIG_INVALID` before anything is sent: `https://dev.azure.com` with no organization\nor with more after it (a project), or a `visualstudio.com` URL with any path other\nthan the legacy `/DefaultCollection`.\n\n```bash\nexport TOIL_ADO_CLOUD_BASE_URL=https://dev.azure.com/imagile\nexport TOIL_ADO_CLOUD_PAT=<your organization-scoped token>\n```\n\nOr `~/.toil/config.json`, with `project` and `repo` usually set once under\n`defaults.ado-cloud`:\n\n```json\n{\n \"version\": 2,\n \"connections\": {\n \"imagile-ado\": { \"area\": \"ado-cloud\", \"baseUrl\": \"https://dev.azure.com/imagile\", \"writes\": true }\n },\n \"defaults\": { \"ado-cloud\": { \"connection\": \"imagile-ado\", \"project\": \"Imagile\", \"repo\": \"imagile-api\" } }\n}\n```\n\nThe token never goes in this file; a plaintext one there is refused with\n`CONFIG_INVALID`. Run `toil connections add imagile-ado --area ado-cloud` (or\n`toil connections login imagile-ado`) to keep it in the OS credential store, or set\n`TOIL_ADO_CLOUD_PAT`. Env vars always win over the file. For a second organization,\nadd a second connection with its own token.\n\n**In Azure Pipelines**, map the job's own token and organization URL into the step:\n\n```yaml\n- script: toil ado-cloud work-item get 42\n env:\n TOIL_ADO_CLOUD_PAT: $(System.AccessToken)\n TOIL_ADO_CLOUD_BASE_URL: $(System.CollectionUri)\n```\n\n`ado-cloud` doesn't read `SYSTEM_ACCESSTOKEN` or `SYSTEM_COLLECTIONURI` on its own.\nAzure Pipelines sets both under the same names on Server and on Services, and the\n`ado` area already takes `SYSTEM_ACCESSTOKEN`, so if both areas read them, one job's\ntoken would configure both. The job token has to be mapped into the step's\nenvironment anyway, so naming it `TOIL_ADO_CLOUD_PAT` costs nothing. On Services,\n`System.CollectionUri` is the organization URL with a trailing slash\n(`https://dev.azure.com/imagile/`), which `baseUrl` accepts.\n\n## Where a command acts\n\n`--project <name>` and `--repo <name>` are group flags, accepted before or after the\ncommand (`toil ado-cloud --project Imagile work-item search --wiql ...`). Without them,\ntoil uses a dossier, then the connection's `project` and `repo`. The git remote isn't\nread. Over MCP they're the `project` and `repo` fields. `meta.context` says where each\ncame from.\n\n- A work item belongs to the organization, so `work-item get`, `work-item update`,\n `work-item transition`, `work-item history` and `work-item get-many` need neither.\n- `work-item create`, `work-item search`, `work-item comments`, `work-item comment`,\n `work-item iterations` and `repo list` need a project.\n- `repo get` and every `pr` command need a project and a repo.\n- `work-item states` needs a project.\n- Every `sprint`, `backlog` and `board` command needs a project and acts for one\n team: `--team <name or id>` on the command (not the group; `team` over MCP), else a\n dossier's or the connection's `team`, else the project's default team, which toil\n reads from the project first (one extra request) and names in an\n `ADO_CLOUD_DEFAULT_TEAM` warning.\n- `whoami`, `project list` and `project get` need neither.\n\n## Commands\n\nCommands are `toil ado-cloud <resource> <action> [ids...] [--flags]`; ids are\npositional. Every command also takes `--connection <name>`. Write commands (marked \u270E)\nneed `writes: true` on the connection **and** `--allow-write`. Names and flags match\n`ado` wherever the operation is the same. MCP tools are `ado_cloud_<command>`\n(`ado_cloud_work_item_get`), and a positional id is the `id` field. There are no\ndeletes.\n\n| Command | Flags | Returns |\n|---------|-------|---------|\n| `whoami` | | The token's connection data; `authenticatedUser.id` is the identity id the vote commands use |\n| `project list` | `--limit --cursor` | Projects in the organization |\n| `project get <name>` | | One project by name or id |\n| `repo list` | | Git repositories in the project |\n| `repo get` | | The repository |\n| `work-item get <id>` | | A work item with every field and relation |\n| `work-item get-many <id...>` | `--fields` | `{ count, value, missing }` for several ids |\n| `work-item create` \u270E | `--type --title --description --assignee --priority --field` | The created work item |\n| `work-item update <id>` \u270E | `--field --rev` | The updated work item |\n| `work-item transition <id>` \u270E | `--state` or `--to` | The updated work item; with `--to` (`start`, `review`, `done`, `reopen` or a state name), resolved against the states the item's own type has, `meta.transition` says what it resolved to |\n| `work-item search` | `--wiql --updated-since --limit --cursor` | The WIQL answer: matching ids and urls, not fields |\n| `work-item history <id>` | `--limit --cursor` | Every revision, oldest first |\n| `work-item comments <id>` | `--limit --cursor` | Every comment on the work item |\n| `work-item comment <id>` \u270E | `--body` | The new comment |\n| `work-item iterations` | `--depth` | The iteration tree, with dates |\n| `work-item states` | `--type` | The states of `--type`, with their categories |\n| `sprint list` | `--team --state` | The team's sprints, each with its `timeFrame` (past, current, future) |\n| `sprint items <id>` | `--team` | The work items in one sprint, as ids with their parent links |\n| `backlog list` | `--team` | The team's backlog levels |\n| `backlog items <id>` | `--team` | The work items on one backlog level, in backlog order, as ids |\n| `board list` | `--team` | The team's boards |\n| `board get <id>` | `--team` | One board, with its columns and the state each holds |\n| `pr list` | `--state --creator --reviewer --created-after --created-before --updated-since --limit --cursor` | Pull requests |\n| `pr get <id>` | `--include` | One pull request, with `included` lists when asked |\n| `pr create` \u270E | `--title --source --target --description --reviewers --draft` | The created pull request |\n| `pr update <id>` \u270E | `--title --description --target --draft` | The updated pull request |\n| `pr merge <id>` \u270E | `--strategy --delete-source --message` | The pull request, with completion requested |\n| `pr abandon <id>` \u270E | | The abandoned pull request |\n| `pr reviewers <id>` | | Reviewers and their votes |\n| `pr approve <id>` \u270E | | Your reviewer entry, vote 10 |\n| `pr unapprove <id>` \u270E | | Your reviewer entry, vote 0 |\n| `pr wait-for-author <id>` \u270E | | Your reviewer entry, vote -5 |\n| `pr threads <id>` | | Comment threads, as the server returns them |\n| `pr comments <id>` | `--inline-only --general-only --include-system` | Every comment, flattened from the threads |\n| `pr comment <id>` \u270E | `--body` | The new thread |\n| `pr comment-inline <id>` \u270E | `--file --line --body --line-type` | The new thread, on one line of a file |\n| `pr reply <id> <thread-id>` \u270E | `--body` | The new reply |\n| `pr resolve <id> <thread-id>` \u270E | `--status` | The thread, with its new status |\n| `api` | `<method> <path>`, `--query --body-file --content-type` | Any endpoint (below) |\n\n```bash\ntoil ado-cloud --project Imagile work-item search --wiql \"SELECT [System.Id] FROM WorkItems\" --updated-since 2026-10-01 --limit 200\ntoil ado-cloud work-item get-many 42 7 --fields System.Title,System.State\ntoil ado-cloud --project Imagile work-item create --type Bug --title \"Login broken\" --field storypoints=3 --allow-write\ntoil ado-cloud work-item update 42 --field state=Active --rev 3 --allow-write\ntoil ado-cloud work-item transition 42 --to review --allow-write\ntoil ado-cloud --project Imagile --repo imagile-api pr list --state all --limit 50\ntoil ado-cloud --project Imagile --repo imagile-api pr list --state all --updated-since 2026-10-01 --limit 100\ntoil ado-cloud --project Imagile --repo imagile-api pr get 42 --include reviews,checks,commits,files\ntoil ado-cloud --project Imagile --repo imagile-api pr merge 42 --strategy squash --delete-source --allow-write\ntoil ado-cloud --project Imagile --repo imagile-api pr reply 42 7 --body \"Fixed in the next commit.\" --allow-write\ntoil ado-cloud --project Imagile sprint list --state current\ntoil ado-cloud --project Imagile board get \"Backlog items\" --team \"Imagile Team\"\n```\n\n### Paging\n\n`project list`, `pr list`, `work-item search`, `work-item history` and\n`work-item comments` return the whole list by default. With `--limit <n>` they return\nat most that many and set `meta.page.nextCursor`; pass it back as `--cursor`, with the\nsame `--limit`, for the next page, until it's `null`. Every list except `work-item search`\nreads page by page (continuation tokens for projects and comments, `$top` and `$skip`\nfor pull requests and revisions) and stops with an `HTTP` error after 1,000 pages,\nnaming the list.\n\n### Work items\n\n- **Fields.** `--field name=value` takes a reference name\n (`Microsoft.VSTS.Scheduling.StoryPoints=5`) or an alias, matched ignoring case,\n spaces and dashes: the connection's `fieldAliases` first, then the built-in ones\n (`title`, `state`, `assignedto`, `description`, `areapath`, `iterationpath`,\n `iteration`, `tags`, `priority`, `severity`, `effort`, `storypoints`,\n `remainingwork`, `remaining`, `acceptancecriteria`, `reprosteps`). Anything else is\n sent as given. Values are sent as text; the server converts them.\n- **`work-item update <id> --rev <n>`** adds a JSON Patch `test` of the revision first, so the\n server refuses the whole change if someone else changed the item since you read it.\n- **`work-item search`** returns the matching ids and urls, not their fields; fetch\n those with `work-item get-many`. `--updated-since <iso>` keeps only items changed at or after\n that instant: a date (`2026-10-01`, UTC midnight) or a date-time with its zone\n (`2026-10-01T09:00:00Z`). toil ANDs `[System.ChangedDate] >= '<instant>'` onto the\n query's own `WHERE`, in parentheses so an `OR` keeps its meaning, and asks for time\n precision. Time precision applies to the whole query, so with `--updated-since` an\n `=` on a date field matches one exact instant, not a day; write date conditions with\n `>=` and `<` instead. It and `--limit` work on flat queries (`FROM WorkItems`) only;\n a link query is refused. With `--limit`, each page runs the query again, so an item\n changed in between can move. A query returns at most 20,000 items.\n- **`work-item get-many <id...>`** reads 200 ids per request, at most 1,000 per\n call. `value` holds the items found in the order asked, with every field and\n relation, or only `--fields`; `missing` lists each id that doesn't exist or the\n token can't see, with an `ADO_CLOUD_WORK_ITEMS_MISSING` warning.\n- **`work-item history`** returns each revision as the whole item as it stood after that\n change, oldest first, so neighbours show what changed and when.\n\n### Sprints, backlogs and boards\n\nThese read a team's settings, which is where Azure DevOps keeps what its boards are\nbuilt from. Each returns the server's own JSON (a list's `value`, or the whole body).\n\n- **`sprint list`** returns the sprints the team has selected, in the team's order:\n `id`, `name`, `path` and `attributes { startDate, finishDate, timeFrame }`.\n `timeFrame` is `past`, `current` or `future`, and the team settings set it even when\n the sprint has no dates, so this is how to tell which sprint is current; the\n iteration tree (`work-item iterations`) carries dates only where someone set them.\n `--state current` (or a comma-separated list of `past`, `current`, `future`) keeps\n only those; anything else is `INVALID_INPUT`.\n- **`sprint items <id>`** takes a sprint's `id` from `sprint list` and returns\n `workItemRelations`: each `{ rel, source, target: { id, url } }`, with `rel` and\n `source` null for a top-level item and `System.LinkTypes.Hierarchy-Forward` with the\n parent as `source` for a child. Ids only: fetch fields with `work-item get-many`.\n- **`backlog list`** returns the backlog levels: `id` (a category reference name such\n as `Microsoft.RequirementCategory`), `name`, `rank`, `type`, `workItemTypes`,\n `defaultWorkItemType`, `columnFields` and `isHidden`. **`backlog items <id>`** returns\n that level's `workItems` in backlog (priority) order, each `{ rel, source, target: {\n id } }`.\n- **`board list`** returns the boards, one per backlog level (`id`, `name`, `url`).\n **`board get <id>`** takes the id or the name and returns the board's `columns`, each\n `{ id, name, itemLimit, columnType, stateMappings, isSplit }`, its `rows`\n (swimlanes), `allowedMappings` and `fields`. A team can rename its columns (To Do,\n Doing, Testing, Done over New, Approved, Committed, Done), so the column an item sits\n in can't be worked out from its state: `stateMappings` (`{ \"<work item type>\":\n \"<state>\" }`) says which state each column holds.\n- **`work-item states --type <type>`** returns the type's states, each `{ name, color,\n category }`, in workflow order. `category` (`Proposed`, `InProgress`, `Resolved`,\n `Completed`, `Removed`) is how a custom state is classified. A type the project\n doesn't have answers with no states rather than an error, so toil adds an\n `ADO_CLOUD_TYPE_UNKNOWN` warning.\n\n### Pull requests\n\n- Branch names get `refs/heads/`; a full ref (`refs/heads/x`, `refs/tags/x`) is sent as\n given. `--reviewers` and `--creator` / `--reviewer` take identity ids (from\n `whoami`, or a pull request's `reviewers[].id`), not names or emails.\n- `--created-after` and `--created-before` take a date (UTC midnight) or a date-time\n with its zone, as `--updated-since` does.\n- `pr list --updated-since <iso>` keeps every pull request that is still active, plus\n those created or closed at or after that instant. Azure DevOps records no\n last-updated time on a pull request (only `creationDate` and `closedDate`), so this\n is a superset of what changed: a sync that merges by `pullRequestId` misses nothing.\n It combines with the other filters, and `--limit` counts the pull requests it keeps.\n- `pr get <id> --include <list>` adds `data.included`, holding only the lists asked\n for (comma-separated, any case), each every page of Azure DevOps' own records:\n `reviews` (the comment threads, where each vote change is a system comment in a\n thread whose `properties.CodeReviewThreadType` is `VoteUpdate`, beside each\n reviewer's comments with `publishedDate`), `checks` (the pull request's statuses),\n `commits`, and `files` (the `changeEntries` of the latest iteration). Each list\n costs one or more extra requests; an unknown name is refused before any request.\n- `pr merge` reads the pull request for its source commit, then asks the server to\n complete it with `--strategy noFastForward` (default), `squash`, `rebase` or\n `rebaseMerge`. A pull request with no source commit yet is refused with\n `INVALID_INPUT` before anything is changed. Completion is asynchronous: check `data.status` and\n `data.mergeStatus`, which stay `active` and `queued` while policies or conflicts\n hold it.\n- `pr update` doesn't change reviewers: the API doesn't take them on that call.\n- `pr comments` flattens every live thread's comments, oldest first, each with\n `threadId` and `threadContext` (null for a general comment). System comments (votes,\n pushes) are left out unless `--include-system`. `pr threads` returns the\n threads themselves, system ones included.\n- `pr comment-inline` anchors on the right (new) side of `--line` unless\n `--line-type left`; a path without a leading `/` gets one.\n- `pr resolve` sets `--status fixed` (resolved) by default; `wontFix`,\n `closed`, `byDesign`, `pending`, or `active` to reopen.\n\n## Output, compared with `ado`\n\n`data` is the server's own JSON, so where Services and Server agree it has the same\nshape as `ado`'s, and `toil util owi map` reads `work-item get`, `work-item get-many`,\n`work-item history` and `work-item iterations` output from either area into Open Work\nItems. The differences, for anything that reads both:\n\n- **Work items** (`work-item get`, `work-item get-many`, `work-item history`,\n `work-item search`) have\n the same shape: `id`, `rev`, `fields` keyed by reference name, `relations`, `url`.\n On Services every `url` is under the organization (`https://dev.azure.com/<org>/_apis/...`)\n with no collection segment. `work-item get-many` returns `{ count, value, missing }`,\n the same as `ado`'s.\n- **Identities** (`System.AssignedTo`, `System.CreatedBy`, `createdBy`, `reviewers`)\n are the same object, `{ displayName, id, uniqueName, url, imageUrl, descriptor }`,\n but on Services `uniqueName` is the user's sign-in email, `descriptor` starts with\n `aad.` (or `msa.`), and `url` is on `vssps.dev.azure.com`. On Server `uniqueName` is\n often `DOMAIN\\user`.\n- **`work-item comments`** returns every comment, following continuation tokens;\n `ado`'s returns only the server's first page. Each comment has the same shape.\n- **`work-item create`** takes `--type`, `--title` and the other flags, and `--field`; it\n has no `--input-file` or `--parent`, which `ado`'s has.\n- **`work-item update`** takes `--field` (and `--rev`); it has no `--input-file`.\n- **`pr comments`** leaves system comments out unless `--include-system`;\n `ado`'s includes them.\n- **Ids** are whole numbers, checked by the schema: `work-item get 12abc` is refused, where\n `ado` reads it as 12.\n\n## Any endpoint: `ado-cloud api`\n\nWhen no command above covers an endpoint, `ado-cloud api` calls it directly. It sends\nthe connection's own token, the same way every other `ado-cloud` command does, to a\npath under the organization URL. Add `api-version` yourself:\n\n```bash\ntoil ado-cloud api GET _apis/projects --query api-version=7.1\ntoil ado-cloud api GET Imagile/_apis/wit/workitemtypes --query api-version=7.1 --query '$expand=states'\ntoil ado-cloud api PATCH _apis/wit/workitems/42 --query api-version=7.1 --body-file patch.json --content-type application/json-patch+json --allow-write\n```\n\n- **The path** is relative to `baseUrl`, with or without a leading `/` (in Git Bash\n on Windows, leave it off: the shell rewrites `/_apis/...` into a file path, which is\n refused). A full URL, a scheme, `//host`, a leading backslash or a `.` / `..`\n segment is refused with `INVALID_INPUT` before anything is sent, so the token never\n leaves the connection's host.\n- **The method decides the gate.** `GET` and `HEAD` are reads. `POST`, `PUT`,\n `PATCH` and `DELETE` are writes: they need `writes: true` on the connection\n **and** `--allow-write`. `DELETE` works only on the CLI: over MCP,\n `ado_cloud_api` refuses it with `INVALID_INPUT`.\n- **`--query key=value`** adds a query parameter; repeat it for more, or to repeat\n a key. **`--body-file <path>`** sends that file (inside the workspace, or `-` for\n stdin) as the body, as `application/json` unless `--content-type` says otherwise.\n A work item change is `application/json-patch+json`.\n- **Output:** a JSON body is `data`, parsed. A text body (`text/*`, XML, or no content\n type) is `data` as text. Any other body is binary: `data` is its bytes as base64,\n with an `API_BINARY` warning. Text and binary are capped at 1 MB, with an\n `API_TRUNCATED` warning when the body was longer. An empty body (a `204`, a `HEAD`)\n is `null`. `meta.response` is `{ status, contentType }`. Errors use the usual codes\n (`AUTH`, `NOT_FOUND`, `HTTP`, `NETWORK`) with Azure DevOps's own message. A body\n labelled JSON that doesn't parse comes back as text, with an `API_NOT_JSON` warning.\n- **Over MCP** it's the `ado_cloud_api` tool, with `method`, `path`, `query` (an array\n of `key=value` strings), `bodyFile`, `contentType` and `allowWrite`.\n\nPrefer a wrapped command when one exists: it knows the endpoint's paging and quirks,\nand `ado-cloud api` doesn't.\n\n## Notes\n\n- `toil connections test` reads the organization's connection data, which names the\n token's own user.\n- A 429 is retried after the delay Azure DevOps asks for, as in every area.\n- Not covered yet: pipelines and builds, attachments, work item types and fields,\n areas, links, tags, team capacity and settings changes, and PR files and diffs.\n `ado-cloud api` reaches all of them.\n",
140318
- "ado.md": '---\narea: ado\ndescription: Work items, git repositories, pull requests and pipelines on Azure DevOps Server\n---\n\n# Azure DevOps Server (`ado`)\n\nWork items, git repositories, pull requests and pipelines on **Azure DevOps Server**\n(on-premises), through its REST API with `api-version=7.1`. Verification level:\n`unit`.\n\n**Supported versions:** Azure DevOps Server 2022.1 or later (REST API 7.1). Requests\nsend `api-version=7.1` (`7.1-preview.1` for connection data, `7.1-preview.4` for work\nitem comments), which newer servers also accept. Azure DevOps Server 2022 RTM, 2020\nand 2019 are out of scope: an older server\'s "REST API version out of range" answer\ncomes back as an error saying the server is too old for toil and naming 2022.1.\n\n## Credential\n\nAn Azure DevOps **personal access token**: in Azure DevOps, User settings \u2192 Personal\naccess tokens \u2192 New Token. Give it the scopes the commands you\'ll use need (Work\nItems, Code, Build; Read & write for the write commands). toil sends it as\n`Authorization: Basic base64(":" + token)`, with an empty user name. There is no\npassword or browser login.\n\nIn an Azure Pipelines job, the job\'s own token, `SYSTEM_ACCESSTOKEN`, is read when\n`TOIL_ADO_PAT` isn\'t set (for the default connection, and before anything in the\nconfig file), so a pipeline step needs only `TOIL_ADO_BASE_URL`. Map it into the\nstep\'s environment (`env: SYSTEM_ACCESSTOKEN: $(System.AccessToken)`).\n\n## Configuration\n\n| Key | Env var | Required | Meaning |\n|-----|---------|----------|---------|\n| `baseUrl` | `TOIL_ADO_BASE_URL` | yes | Server root, e.g. `https://ado.imagile.dev` (keep any context path, such as `/tfs`) |\n| `pat` | `TOIL_ADO_PAT` (or `SYSTEM_ACCESSTOKEN`) | yes | Personal access token |\n| `collection` | `TOIL_ADO_COLLECTION` | no | Default collection, when `--collection` isn\'t given |\n| `project` | `TOIL_ADO_PROJECT` | no | Default team project, when `--project` isn\'t given |\n| `repo` | `TOIL_ADO_REPO` | no | Default git repository, when `--repo` isn\'t given |\n| `fieldAliases` | `TOIL_ADO_FIELD_ALIASES` | no | Work item field aliases as a JSON object, friendly name to reference name, e.g. `{"storypoints": "Microsoft.VSTS.Scheduling.StoryPoints"}` |\n| `discoveredFields` | `TOIL_ADO_DISCOVERED_FIELDS` | no | Fields an earlier discovery recorded; kept, not read |\n| `discoveredTypes` | `TOIL_ADO_DISCOVERED_TYPES` | no | Work item types an earlier discovery recorded; kept, not read |\n| `writes` | `TOIL_ADO_WRITES` | no | `true` lets write commands run (with `--allow-write`) |\n\nEnvironment variables (CI, or a one-off shell):\n\n```bash\nexport TOIL_ADO_BASE_URL=https://ado.imagile.dev\nexport TOIL_ADO_PAT=<your personal access token>\n```\n\nOr `~/.toil/config.json`, with `collection`, `project` and `repo` usually set once\nunder `defaults.ado`:\n\n```json\n{\n "version": 2,\n "connections": {\n "corp-ado": { "area": "ado", "baseUrl": "https://ado.imagile.dev", "writes": true }\n },\n "defaults": { "ado": { "connection": "corp-ado", "collection": "DefaultCollection", "project": "Imagile", "repo": "imagile-api" } }\n}\n```\n\nThe token never goes in this file; a plaintext one there is refused with\n`CONFIG_INVALID`. Run `toil connections add corp-ado --area ado` (or\n`toil connections login corp-ado` for an existing connection) to keep it in the OS\ncredential store, or set `TOIL_ADO_PAT`.\n\n## Where a command acts\n\n`--collection <name>` (or its alias `--organization <name>`), `--project <name>` and\n`--repo <name>` are group flags, accepted before or after the command\n(`toil ado --project Imagile work-item get 42`). Without them, toil reads them from\nthe first of the workspace\'s remotes on the connection\'s host, of any name, trying\n`origin` first\n(`https://<host>[/tfs]/<collection>/<project>/_git/<repo>`, or the `_ssh` forms with\n`ssh://git@<host>` or `git@<host>:`), then the connection\'s `collection`, `project`\nand `repo` settings. `--collection` beats `--organization`, which beats the remote and\nthe settings. An `ssh://` remote with no user, an HTTPS remote with a user name, and\nthe short `<collection>/_git/<project>` form aren\'t read correctly. `meta.context`\nsays where each came from.\n\n**Every command needs a collection and a project**, even the ones that don\'t use\nthem (`whoami`, `collection list`), and fails with "Could not determine Azure\nDevOps collection" (or project) when either is missing. Every `repo` and `pr` command\nexcept `repo list` and `repo create` also needs a repo.\n\nIds are read as whole numbers from the start of the text: `12abc` is 12, and `abc` is\nsent as `NaN`.\n\n## Commands\n\nCommands are `toil ado <resource> <action> [ids...] [--flags]`. Ids are positional:\nthe resource\'s id first, then a sub-item\'s (attachment, thread, comment).\n\nServer and projects:\n\n- `whoami`, `connection-data`: The collection\'s connection data: the authenticated\n user (`authenticatedUser.id` is the identity id the vote commands use), the instance\n and the deployment. The two return the same thing.\n- `collection list`: The server\'s project collections.\n- `project list`: Every team project in the collection.\n- `project get <name>`: One team project by name.\n\nWork items (`<id>` is the work item id):\n\n- `work-item get <id>`: A work item with every field and relation.\n- `work-item create`: Create one (`--type`, `--title`, `--description`, `--assignee`,\n `--priority`, `--field name=value` repeatable, `--input-file`). `--parent <id>`\n adds a parent link afterwards; the result is the item as created, and a failed link\n is only an `ADO_PARENT_LINK_FAILED` warning, with the item already created.\n- `work-item update <id>`: Set fields (`--field name=value` repeatable, or\n `--input-file`).\n- `work-item transition <id>`: Set `--state`, or `--to <intent-or-status>` (`start`,\n `review`, `done`, `reopen` or a state name), resolved against the states the item\'s\n own type has (`core.md`, **Moving work items by intent**).\n- `work-item assign <id>`: Assign to `--assignee`, a display name or email.\n- `work-item link <id>`: Link it to `--target <id>`, `--type related` (default),\n `parent`, `child`, `duplicate`, `duplicate-of`, or a raw relation name.\n- `work-item search`: Run `--wiql`; returns the matching ids and urls, not their\n fields. `--updated-since <iso>` keeps only items changed at or after that instant: a\n date (`2026-10-01`, UTC midnight) or a date-time with its zone\n (`2026-10-01T09:00:00Z`). toil ANDs `[System.ChangedDate] >= \'<instant>\'` onto the\n query\'s own `WHERE`, in parentheses so an `OR` keeps its meaning, and asks the\n server for time precision. Time precision applies to the whole query, so with\n `--updated-since` an `=` on a date field (`[System.CreatedDate] = @Today`) matches\n one exact instant, not a day; write date conditions with `>=` and `<` instead.\n It and `--limit` work on flat queries (`FROM WorkItems`) only; a link query is\n refused. With `--limit`, each page runs the query again, so an item changed in\n between can move. A query returns at most 20,000 items, so a page can\'t end past\n that.\n- `work-item get-many <id...>`: Several work items through the batch endpoint, 200 ids\n per request, at most 1,000 per call. Returns `{ count, value, missing }`: `value`\n holds the items found in the order asked, with every field and relation, or only\n `--fields System.Title,System.State`; `missing` lists each id that doesn\'t exist or\n the token can\'t see, with an `ADO_WORK_ITEMS_MISSING` warning.\n- `work-item history <id>`: Every revision of a work item, oldest first; each is the\n whole item as it stood after that change, so neighbours show what changed and when.\n- `work-item comments <id>`, `work-item comment <id>` (`--body`): Comments; listing\n reads the first page only.\n- `work-item tag <id>`, `work-item untag <id>`: `--tags a;b` or `a,b`, matched\n ignoring case. The tag list is read and written back, with no revision check.\n- `work-item attachments <id>`: The attached files (id, name, url, size, dates).\n- `work-item attach <id>`: Upload `--file` (a path in the workspace), then link it\n (`--comment` optional). Returns the uploaded attachment\'s `{ id, url }`. If the link\n fails, the upload stays on the server.\n- `work-item download <id> <attachment-id>`: Save the attachment to `--dir` (default\n `.toil`) in the workspace; returns `{ saved, name, size }`. It never overwrites a\n file. A name Windows would read as another file is saved as one it won\'t: a device\n name such as `CON` gets a leading `_`, a `:` and what follows it is dropped, as are\n trailing dots and spaces. The token only goes to the configured host: an attachment URL naming another\n host is fetched from the configured one, with an `ADO_ATTACHMENT_HOST` warning.\n- `work-item areas`, `work-item iterations`: The area or iteration tree, `--depth`\n (default 10).\n- `work-item types`: The work item types with their states and required fields.\n- `work-item states`: The states of `--type`.\n- `work-item fields`: The collection\'s fields, or with `--type` a type\'s (those have\n no `type` or `readOnly`); `--custom-only` drops `System.*` and `Microsoft.VSTS.*`.\n- `work-item schema`: The `--input-file` JSON schema and an example; `--example-only`\n returns just the example as `data`. Needs no connection.\n\n`work-item types` and `work-item fields` have no `--save`; passing it is an unknown\noption. The aliases `--save` would store are the built-in ones below, which apply\nanyway. `--discover` is accepted and changes nothing.\n\nField names in `--field` and `--input-file` resolve through the connection\'s\n`fieldAliases`, then the built-in aliases (`title`, `state`, `description`,\n`priority`, `storypoints`, `acceptancecriteria`, `reprosteps` and others), matched\nignoring case, spaces and dashes; anything else is sent as a reference name\n(`MyOrg.Team`). To add your own alias, set `fieldAliases` as a JSON object:\n`toil connections add <name> --area ado` asks for it when setting up a connection;\non one that exists, add `"fieldAliases": { "effortdays": "MyOrg.EffortDays" }` to it\nin `~/.toil/config.json`, or set `TOIL_ADO_FIELD_ALIASES` (or\n`TOIL_CONN_<NAME>_FIELD_ALIASES`) to the JSON. An `--input-file` is\n`{ "type": "Bug", "fields": { "Title": "...", "Description": "@desc.html" } }`: a value\nstarting with `@` is read from that file. Flags win over the file, with an\n`ADO_INPUT_OVERRIDDEN` warning naming the keys.\n\nRepositories:\n\n- `repo list`, `repo create` (`--name`), `repo get`: Repositories in the project.\n- `repo default-reviewers`: Required reviewers policies covering the repository.\n- `commit status <commit>`: Statuses posted to a commit.\n\nPull requests (`<id>` is the pull request id):\n\n- `pr list`: Every pull request, `--state active` (default), `abandoned`,\n `completed` or `all`. `--creator` and `--reviewer` are sent as identity id filters,\n so pass an id (from `whoami`), not an alias. `--created-after` and\n `--created-before` take ISO 8601 dates; a date alone is UTC midnight, a date-time\n without a zone is local time. `--updated-since <iso>` (the same date forms) keeps\n every pull request that is still active, plus those created or closed at or after\n that instant. Azure DevOps records no last-updated time on a pull request (only\n `creationDate` and `closedDate`), so this is a superset of what changed: a sync\n that merges by `pullRequestId` misses nothing. It combines with the other filters,\n and `--limit` counts the pull requests it keeps.\n- `pr get <id>`: One pull request. `--include <list>` adds `data.included`, holding\n only the lists asked for (comma-separated, any case), each every page of Azure\n DevOps\' own records: `reviews` (the comment threads, where each vote change is a\n system comment in a thread whose `properties.CodeReviewThreadType` is `VoteUpdate`,\n beside each reviewer\'s comments with `publishedDate`), `checks` (the pull request\'s\n statuses), `commits`, and `files` (the `changeEntries` of the latest iteration).\n Each list costs one or more extra requests; an unknown name is refused before any\n request.\n- `pr create`: `--title`, `--source`, `--target` (default `main`), `--description`,\n `--reviewers <id,id>` (identity ids), `--draft`. Give branch names without\n `refs/heads/`, which toil adds (a full ref gets it twice).\n- `pr update <id>`: `--title`, `--description`, `--reviewers`, `--draft true|false`,\n in one PATCH.\n- `pr merge <id>`: Ask the server to complete it, `--strategy noFastForward`\n (default), `squash`, `rebase` or `rebaseMerge`, `--delete-source`. Completion is\n asynchronous; check `data.status`.\n- `pr abandon <id>`: Abandon it.\n- `pr comments <id>`: Every comment of every thread, oldest first, with `threadId` and\n `threadContext` (null for a general comment); system comments included.\n `--inline-only` or `--general-only` narrows it.\n- `pr comment <id>` (`--body`), `pr comment-inline <id>` (`--file /src/a.ts`,\n `--line 12`, `--body`, `--line-type left|right`, default `right`),\n `pr reply <id> <thread-id>` (`--body`), `pr resolve <id> <thread-id>` (status\n `fixed`).\n- `pr delete-comment <id> <thread-id> <comment-id>`: Returns `{ "deleted": true }`.\n CLI only: deletes are never exposed through MCP.\n- `pr files <id>`: Changed files of the latest iteration, at most 100.\n- `pr diff <id>`: Changed files between the last merge commits, at most 100; `--path`\n keeps one file (a leading `/` is added).\n- `pr reviewers <id>`: Reviewers and their votes.\n- `pr approve <id>`, `pr unapprove <id>`, `pr wait-for-author <id>`: Vote 10, 0 or -5\n as the token\'s own user.\n- `pr builds <id>`: Builds of the pull request\'s source branch (not of its merge ref).\n\nPipelines and runs:\n\n- `pipeline list`, `pipeline get <id>`: Pipelines (build definitions).\n- `pipeline run <id>`: Queue a run of the pipeline, `--branch` (a short name gets\n `refs/heads/`), `--parameter k=v` repeatable. `--wait` polls every `--poll` seconds\n (10) for up to `--timeout` seconds (600). A result other than `succeeded` still\n returns the build, with an `ADO_BUILD_NOT_SUCCEEDED` warning, and the CLI exits 1.\n The command\'s own time limit is 11 minutes, so a longer `--timeout` also needs\n `TOIL_TIMEOUT_MS`.\n- `run list`: Runs, `--definition <id>` or `--name <pipeline>`, `--branch` (as given,\n e.g. `refs/heads/main`), `--status`, `--top` (default 50; `--top 0` lists every\n run).\n- `run get <id>`, `run cancel <id>`: One run; cancel it.\n- `run logs <id>`: The run\'s logs; with `--log-id`, that log\'s text as\n `{ "log": "..." }`.\n\nPaging: `project list`, `pipeline list`, `run list`, `pr list`, `pr builds`,\n`work-item search` and `work-item history` return the whole list by default. With\n`--limit <n>` they return at most that many and set `meta.page.nextCursor`; pass it\nback as `--cursor`, with the same `--limit`, for the next page, until it\'s `null`.\n`run list` takes `--limit` or `--top`, not both. Every list except `work-item search`\n(one request) reads page by page and stops with an `HTTP` error after 1,000 pages,\nnaming the list.\n\nWrite commands need `writes: true` on the connection and `--allow-write` on the call.\n\n```bash\ntoil ado --collection DefaultCollection --project Imagile work-item get 42\ntoil ado work-item create --type Bug --title "Login broken" --field "Story Points=3" --allow-write\ntoil ado work-item link 42 --target 7 --type child --allow-write\ntoil ado --repo imagile-api pr list --state all\ntoil ado --repo imagile-api pr list --state all --updated-since 2026-10-01T00:00:00Z --limit 100\ntoil ado --repo imagile-api pr get 42 --include reviews,checks,commits,files\ntoil ado pr comment-inline 42 --file /src/app.ts --line 12 --body "Off by one?" --allow-write\ntoil ado work-item search --wiql "SELECT [System.Id] FROM WorkItems" --updated-since 2026-10-01 --limit 200\ntoil ado work-item get-many 42 7 --fields System.Title,System.State\ntoil ado pipeline run 5 --branch main --wait --allow-write\ntoil ado run logs 101 --log-id 3\n```\n\nOver MCP the same commands are tools named after the path, with spaces and\nhyphens as underscores (`ado_work_item_get`, `ado_pr_comment_inline`), and a\npositional id is the `id` field.\n\n## Checking a dossier\n\n`check-dossier` checks the call\'s dossier against the server: each team project it names (`project`, per repo or not, and `projects`) exists in its collection, and each repository (`repo`) in its project. The collection is the section\'s `collection`, else `--collection` or the connection\'s; a value with no collection anywhere is `INVALID_INPUT`. It\'s `toil ado check-dossier` (`--dossier <name|file>`, or the dossier the folder resolves to), and it returns `{ dossier, connection, env, ok, checked, checks, unchecked }`, one check per value with its key path. The CLI exits 1 when one is missing. A failure other than not-found (a bad token, an unreachable host) fails the command. Read only.\n',
140419
+ "SKILL.md": "---\nname: toil\ndescription: Use toil, a structured-JSON CLI and MCP server, to read from and (when allowed) write to databases and the enterprise tools an organization runs, such as issue trackers, source hosts, wikis, CI, artifact repositories, scanners and observability. Use when a task needs data from one of those tools or a database, or mentions `toil` commands, `toil mcp`, a toil connection, or a TOIL_* environment variable.\n---\n\n# toil\n\ntoil is the token-efficient alternative to MCP: the same commands as a CLI, each\nreturning one compact envelope, with this skill read a file at a time rather than\nevery tool schema up front. Keep it lean: `--select` the fields you need, and\n`toil wait` rather than polling.\n\nIf `toil version` doesn't print an envelope, toil isn't installed yet: `install.md`,\nbeside this file, says how.\n\n## Every call\n\n- **Output.** Every command prints one JSON envelope on stdout: `{ ok, data, error,\n meta }`. Check `ok`; on failure, `error.code` says what kind of failure it was and\n `error.fix` what to do about it. `meta.warnings` lists what's worth knowing that\n isn't a failure, and `meta.page.nextCursor` the next page, when there is one.\n- **Two front doors, one command.** `toil <area> <command>` on the command line, or\n the MCP tool named after its path (`db_query`) from `toil mcp --areas <area>`, with\n identical inputs and output.\n- **Writes.** Reads are always allowed. A command that changes data needs\n `writes: true` on the connection, set by a person, and `--allow-write` on the call\n (`allowWrite: true` over MCP). Only make a write the user asked for. Four writes\n differ, each listed in `core.md` under **Writes**.\n- **Connections.** Environment variables always win over `~/.toil/config.json`.\n `--connection <name>` picks one when an area has several; `toil connections list`\n names them, never a secret. Setting one up is for a person: a bare `toil` in a\n terminal opens a menu.\n- **Untracked work.** Before work no ticket covers, rank open tickets with\n `toil util owi similar --query`, then ask the person where it goes: `core.md`,\n **Ticket the work**.\n- **Files** a command reads or writes stay inside the workspace (`--workspace <dir>`,\n else the working directory).\n- **Feedback** to Imagile (`toil feedback`) only when the user asks, scrubbed of\n company data, shown to them in full with its disclaimer, and sent with `--consent`\n only after their yes to that exact report: `core.md`, **Feedback**.\n- **Less output.** `--select <expression>` keeps only the fields you name, and\n `toil wait --until <expression> -- <read>` repeats a read until it's true, instead\n of polling yourself. For any search or listing that may return more than a page,\n add `--summary-file <file>` (`summaryFile`): the full result goes to the file and\n you get a sample with stats; `--output-format toon` makes tables smaller still.\n\n## Where to look\n\nOpen only the file the task needs; each sits beside this one.\n\n| File | When |\n|------|------|\n| `core.md` | `--select`, big results (`--summary-file`, `--output-format toon`), `toil wait`, paging and progress, errors, writes and their exceptions, global flags, files, configuration, the raw `api` passthrough, dossiers, the audit log, calling toil from a program (`@imagile-dev/toil/api`), sending feedback, certificates and proxies |\n| `<area>.md` | One per area, named after it: `jira.md` for `toil jira \u2026`. Its frontmatter says what the area covers; the file gives the oldest version it supports, its credential, its configuration keys and every command |\n| `dossiers.md` | What a dossier is: one body of work mapped to your connections, its file, and how to build and share one |\n| `db.md` | Databases: `toil db \u2026` on every engine |\n| `util.md` | Local utilities with no connection or network: `toil util \u2026` |\n| `skills.md` | Skills marketplaces, and keeping this skill installed |\n| `mcp.md` | Running toil as an MCP server and registering it with an agent |\n| `install.md` | Installing toil, and this skill |\n\n`toil --help` lists the areas this install has.\n",
140420
+ "ado-cloud.md": "---\narea: ado-cloud\ndescription: Work items, boards, backlogs, sprints, git repositories and pull requests on Azure DevOps Services (dev.azure.com)\n---\n\n# Azure DevOps Services (`ado-cloud`)\n\nWork items, a team's boards, backlogs and sprints, git repositories and pull requests\non **Azure DevOps Services** (`https://dev.azure.com/<organization>`, or the older\n`https://<organization>.visualstudio.com`), through its REST API with\n`api-version=7.1`. Built from Microsoft's REST API reference. The work item reads and\nthe team settings commands (sprints, backlogs, boards, work item type states) have\nbeen run against one live Scrum organization; the pull request commands have not.\nVerification level: `unit`.\n\nFor Azure DevOps Server (on-premises), use the `ado` area instead. The two are\nseparate areas so that neither one's fixes can change the other: a Services\nconnection is one organization, where a Server connection is a server holding\nseveral collections.\n\n**Supported versions:** The oldest Azure DevOps Services version toil supports hasn't been established.\nAzure DevOps Services is always current. toil sends `api-version=7.1`, the newest\nreleased version (7.2 is preview only), with `7.1-preview.1` for connection data and\n`7.1-preview.4` for work item comments, which exist only as previews.\n\n## Credential\n\nAn **organization-scoped personal access token**: in Azure DevOps, User settings \u2192\nPersonal access tokens \u2192 New Token, with **Organization** set to the one organization\nthis connection is for. Give it the scopes the commands you'll use need: Work Items\nand Code, Read (or Read & write for the write commands), plus Project and Team Read\nfor `project list`, `project get`, and the `sprint`, `backlog` and `board` commands\nwhen no team is given (toil reads the project for its default team). toil sends it as `Authorization: Basic base64(\":\" + token)`, with\nan empty user name.\n\n**Don't create a global token** (\"All accessible organizations\"). Microsoft is retiring\nglobal personal access tokens: every existing one stops working on **December 1,\n2026**. A connection is one organization, so an organization-scoped token is all it\nneeds. A `401` or `403` is `AUTH`, and its fix says to create an organization-scoped\ntoken and that global ones are being retired.\n\nThere is no OAuth, Microsoft Entra ID or service principal sign-in: those need a\nbrowser login or an app registration, and toil takes only a token you create once.\n\n## Configuration\n\n| Key | Env var | Required | Meaning |\n|-----|---------|----------|---------|\n| `baseUrl` | `TOIL_ADO_CLOUD_BASE_URL` | yes | Organization URL: `https://dev.azure.com/<organization>` (or `https://<organization>.visualstudio.com`) |\n| `pat` | `TOIL_ADO_CLOUD_PAT` | yes | Organization-scoped personal access token (a secret) |\n| `project` | `TOIL_ADO_CLOUD_PROJECT` | no | Default project, when `--project` isn't given |\n| `repo` | `TOIL_ADO_CLOUD_REPO` | no | Default git repository, when `--repo` isn't given |\n| `team` | `TOIL_ADO_CLOUD_TEAM` | no | Default team for the `sprint`, `backlog` and `board` commands, when `--team` isn't given (else the project's default team) |\n| `fieldAliases` | `TOIL_ADO_CLOUD_FIELD_ALIASES` | no | Work item field aliases as a JSON object, friendly name to reference name, e.g. `{\"effortdays\": \"MyOrg.EffortDays\"}` |\n| `writes` | `TOIL_ADO_CLOUD_WRITES` | no | `true` lets write commands run (with `--allow-write`) |\n\nA `baseUrl` that doesn't name exactly one organization is refused with\n`CONFIG_INVALID` before anything is sent: `https://dev.azure.com` with no organization\nor with more after it (a project), or a `visualstudio.com` URL with any path other\nthan the legacy `/DefaultCollection`.\n\n```bash\nexport TOIL_ADO_CLOUD_BASE_URL=https://dev.azure.com/imagile\nexport TOIL_ADO_CLOUD_PAT=<your organization-scoped token>\n```\n\nOr `~/.toil/config.json`, with `project` and `repo` usually set once under\n`defaults.ado-cloud`:\n\n```json\n{\n \"version\": 2,\n \"connections\": {\n \"imagile-ado\": { \"area\": \"ado-cloud\", \"baseUrl\": \"https://dev.azure.com/imagile\", \"writes\": true }\n },\n \"defaults\": { \"ado-cloud\": { \"connection\": \"imagile-ado\", \"project\": \"Imagile\", \"repo\": \"imagile-api\" } }\n}\n```\n\nThe token never goes in this file; a plaintext one there is refused with\n`CONFIG_INVALID`. Run `toil connections add imagile-ado --area ado-cloud` (or\n`toil connections login imagile-ado`) to keep it in the OS credential store, or set\n`TOIL_ADO_CLOUD_PAT`. Env vars always win over the file. For a second organization,\nadd a second connection with its own token.\n\n**In Azure Pipelines**, map the job's own token and organization URL into the step:\n\n```yaml\n- script: toil ado-cloud work-item get 42\n env:\n TOIL_ADO_CLOUD_PAT: $(System.AccessToken)\n TOIL_ADO_CLOUD_BASE_URL: $(System.CollectionUri)\n```\n\n`ado-cloud` doesn't read `SYSTEM_ACCESSTOKEN` or `SYSTEM_COLLECTIONURI` on its own.\nAzure Pipelines sets both under the same names on Server and on Services, and the\n`ado` area already takes `SYSTEM_ACCESSTOKEN`, so if both areas read them, one job's\ntoken would configure both. The job token has to be mapped into the step's\nenvironment anyway, so naming it `TOIL_ADO_CLOUD_PAT` costs nothing. On Services,\n`System.CollectionUri` is the organization URL with a trailing slash\n(`https://dev.azure.com/imagile/`), which `baseUrl` accepts.\n\n## Where a command acts\n\n`--project <name>` and `--repo <name>` are group flags, accepted before or after the\ncommand (`toil ado-cloud --project Imagile work-item search --wiql ...`). Without them,\ntoil uses a dossier, then the connection's `project` and `repo`. The git remote isn't\nread. Over MCP they're the `project` and `repo` fields. `meta.context` says where each\ncame from.\n\n- A work item belongs to the organization, so `work-item get`, `work-item update`,\n `work-item transition`, `work-item history` and `work-item get-many` need neither.\n- `work-item create`, `work-item search`, `work-item comments`, `work-item comment`,\n `work-item iterations` and `repo list` need a project.\n- `repo get` and every `pr` command need a project and a repo.\n- `work-item states` needs a project.\n- Every `sprint`, `backlog` and `board` command needs a project and acts for one\n team: `--team <name or id>` on the command (not the group; `team` over MCP), else a\n dossier's or the connection's `team`, else the project's default team, which toil\n reads from the project first (one extra request) and names in an\n `ADO_CLOUD_DEFAULT_TEAM` warning.\n- `whoami`, `project list` and `project get` need neither.\n\n## Commands\n\nCommands are `toil ado-cloud <resource> <action> [ids...] [--flags]`; ids are\npositional. Every command also takes `--connection <name>`. Write commands (marked \u270E)\nneed `writes: true` on the connection **and** `--allow-write`. Names and flags match\n`ado` wherever the operation is the same. MCP tools are `ado_cloud_<command>`\n(`ado_cloud_work_item_get`), and a positional id is the `id` field. There are no\ndeletes.\n\n| Command | Flags | Returns |\n|---------|-------|---------|\n| `whoami` | | The token's connection data; `authenticatedUser.id` is the identity id the vote commands use |\n| `project list` | `--limit --cursor` | Projects in the organization |\n| `project get <name>` | | One project by name or id |\n| `repo list` | | Git repositories in the project |\n| `repo get` | | The repository |\n| `work-item get <id>` | | A work item with every field and relation |\n| `work-item get-many <id...>` | `--fields` | `{ count, value, missing }` for several ids |\n| `work-item create` \u270E | `--type --title --description --assignee --priority --field` | The created work item |\n| `work-item update <id>` \u270E | `--field --rev` | The updated work item |\n| `work-item transition <id>` \u270E | `--state` or `--to` | The updated work item; with `--to` (`start`, `review`, `done`, `reopen` or a state name), resolved against the states the item's own type has, `meta.transition` says what it resolved to |\n| `work-item search` | `--wiql --updated-since --limit --cursor` | The WIQL answer: matching ids and urls, not fields |\n| `work-item history <id>` | `--limit --cursor` | Every revision, oldest first |\n| `work-item comments <id>` | `--limit --cursor` | Every comment on the work item |\n| `work-item comment <id>` \u270E | `--body` | The new comment |\n| `work-item iterations` | `--depth` | The iteration tree, with dates |\n| `work-item states` | `--type` | The states of `--type`, with their categories |\n| `sprint list` | `--team --state` | The team's sprints, each with its `timeFrame` (past, current, future) |\n| `sprint items <id>` | `--team` | The work items in one sprint, as ids with their parent links |\n| `backlog list` | `--team` | The team's backlog levels |\n| `backlog items <id>` | `--team` | The work items on one backlog level, in backlog order, as ids |\n| `board list` | `--team` | The team's boards |\n| `board get <id>` | `--team` | One board, with its columns and the state each holds |\n| `pr list` | `--state --creator --reviewer --created-after --created-before --updated-since --limit --cursor` | Pull requests |\n| `pr get <id>` | `--include` | One pull request, with `included` lists when asked |\n| `pr create` \u270E | `--title --source --target --description --reviewers --draft` | The created pull request |\n| `pr update <id>` \u270E | `--title --description --target --draft` | The updated pull request |\n| `pr merge <id>` \u270E | `--strategy --delete-source --message` | The pull request, with completion requested |\n| `pr abandon <id>` \u270E | | The abandoned pull request |\n| `pr reviewers <id>` | | Reviewers and their votes |\n| `pr approve <id>` \u270E | | Your reviewer entry, vote 10 |\n| `pr unapprove <id>` \u270E | | Your reviewer entry, vote 0 |\n| `pr wait-for-author <id>` \u270E | | Your reviewer entry, vote -5 |\n| `pr threads <id>` | | Comment threads, as the server returns them |\n| `pr comments <id>` | `--inline-only --general-only --include-system` | Every comment, flattened from the threads |\n| `pr comment <id>` \u270E | `--body` | The new thread |\n| `pr comment-inline <id>` \u270E | `--file --line --body --line-type` | The new thread, on one line of a file |\n| `pr reply <id> <thread-id>` \u270E | `--body` | The new reply |\n| `pr resolve <id> <thread-id>` \u270E | `--status` | The thread, with its new status |\n| `api` | `<method> <path>`, `--query --body-file --content-type` | Any endpoint (below) |\n\n```bash\ntoil ado-cloud --project Imagile work-item search --wiql \"SELECT [System.Id] FROM WorkItems\" --updated-since 2026-10-01 --limit 200\ntoil ado-cloud work-item get-many 42 7 --fields System.Title,System.State\ntoil ado-cloud --project Imagile work-item create --type Bug --title \"Login broken\" --field storypoints=3 --allow-write\ntoil ado-cloud work-item update 42 --field state=Active --rev 3 --allow-write\ntoil ado-cloud work-item transition 42 --to review --allow-write\ntoil ado-cloud --project Imagile --repo imagile-api pr list --state all --limit 50\ntoil ado-cloud --project Imagile --repo imagile-api pr list --state all --updated-since 2026-10-01 --limit 100\ntoil ado-cloud --project Imagile --repo imagile-api pr get 42 --include reviews,checks,commits,files\ntoil ado-cloud --project Imagile --repo imagile-api pr merge 42 --strategy squash --delete-source --allow-write\ntoil ado-cloud --project Imagile --repo imagile-api pr reply 42 7 --body \"Fixed in the next commit.\" --allow-write\ntoil ado-cloud --project Imagile sprint list --state current\ntoil ado-cloud --project Imagile board get \"Backlog items\" --team \"Imagile Team\"\n```\n\n### Paging\n\n`project list`, `pr list`, `work-item search`, `work-item history` and\n`work-item comments` return the whole list by default. With `--limit <n>` they return\nat most that many and set `meta.page.nextCursor`; pass it back as `--cursor`, with the\nsame `--limit`, for the next page, until it's `null`. Every list except `work-item search`\nreads page by page (continuation tokens for projects and comments, `$top` and `$skip`\nfor pull requests and revisions) and stops with an `HTTP` error after 1,000 pages,\nnaming the list.\n\n### Work items\n\n- **Fields.** `--field name=value` takes a reference name\n (`Microsoft.VSTS.Scheduling.StoryPoints=5`) or an alias, matched ignoring case,\n spaces and dashes: the connection's `fieldAliases` first, then the built-in ones\n (`title`, `state`, `assignedto`, `description`, `areapath`, `iterationpath`,\n `iteration`, `tags`, `priority`, `severity`, `effort`, `storypoints`,\n `remainingwork`, `remaining`, `acceptancecriteria`, `reprosteps`). Anything else is\n sent as given. Values are sent as text; the server converts them.\n- **`work-item update <id> --rev <n>`** adds a JSON Patch `test` of the revision first, so the\n server refuses the whole change if someone else changed the item since you read it.\n- **`work-item search`** returns the matching ids and urls, not their fields; fetch\n those with `work-item get-many`. `--updated-since <iso>` keeps only items changed at or after\n that instant: a date (`2026-10-01`, UTC midnight) or a date-time with its zone\n (`2026-10-01T09:00:00Z`). toil ANDs `[System.ChangedDate] >= '<instant>'` onto the\n query's own `WHERE`, in parentheses so an `OR` keeps its meaning, and asks for time\n precision. Time precision applies to the whole query, so with `--updated-since` an\n `=` on a date field matches one exact instant, not a day; write date conditions with\n `>=` and `<` instead. It and `--limit` work on flat queries (`FROM WorkItems`) only;\n a link query is refused. With `--limit`, each page runs the query again, so an item\n changed in between can move. A query returns at most 20,000 items.\n- **`work-item get-many <id...>`** reads 200 ids per request, at most 1,000 per\n call. `value` holds the items found in the order asked, with every field and\n relation, or only `--fields`; `missing` lists each id that doesn't exist or the\n token can't see, with an `ADO_CLOUD_WORK_ITEMS_MISSING` warning.\n- **`work-item history`** returns each revision as the whole item as it stood after that\n change, oldest first, so neighbours show what changed and when.\n\n### Sprints, backlogs and boards\n\nThese read a team's settings, which is where Azure DevOps keeps what its boards are\nbuilt from. Each returns the server's own JSON (a list's `value`, or the whole body).\n\n- **`sprint list`** returns the sprints the team has selected, in the team's order:\n `id`, `name`, `path` and `attributes { startDate, finishDate, timeFrame }`.\n `timeFrame` is `past`, `current` or `future`, and the team settings set it even when\n the sprint has no dates, so this is how to tell which sprint is current; the\n iteration tree (`work-item iterations`) carries dates only where someone set them.\n `--state current` (or a comma-separated list of `past`, `current`, `future`) keeps\n only those; anything else is `INVALID_INPUT`.\n- **`sprint items <id>`** takes a sprint's `id` from `sprint list` and returns\n `workItemRelations`: each `{ rel, source, target: { id, url } }`, with `rel` and\n `source` null for a top-level item and `System.LinkTypes.Hierarchy-Forward` with the\n parent as `source` for a child. Ids only: fetch fields with `work-item get-many`.\n- **`backlog list`** returns the backlog levels: `id` (a category reference name such\n as `Microsoft.RequirementCategory`), `name`, `rank`, `type`, `workItemTypes`,\n `defaultWorkItemType`, `columnFields` and `isHidden`. **`backlog items <id>`** returns\n that level's `workItems` in backlog (priority) order, each `{ rel, source, target: {\n id } }`.\n- **`board list`** returns the boards, one per backlog level (`id`, `name`, `url`).\n **`board get <id>`** takes the id or the name and returns the board's `columns`, each\n `{ id, name, itemLimit, columnType, stateMappings, isSplit }`, its `rows`\n (swimlanes), `allowedMappings` and `fields`. A team can rename its columns (To Do,\n Doing, Testing, Done over New, Approved, Committed, Done), so the column an item sits\n in can't be worked out from its state: `stateMappings` (`{ \"<work item type>\":\n \"<state>\" }`) says which state each column holds.\n- **`work-item states --type <type>`** returns the type's states, each `{ name, color,\n category }`, in workflow order. `category` (`Proposed`, `InProgress`, `Resolved`,\n `Completed`, `Removed`) is how a custom state is classified. A type the project\n doesn't have answers with no states rather than an error, so toil adds an\n `ADO_CLOUD_TYPE_UNKNOWN` warning.\n\n### Pull requests\n\n- Branch names get `refs/heads/`; a full ref (`refs/heads/x`, `refs/tags/x`) is sent as\n given. `--reviewers` and `--creator` / `--reviewer` take identity ids (from\n `whoami`, or a pull request's `reviewers[].id`), not names or emails.\n- `--created-after` and `--created-before` take a date (UTC midnight) or a date-time\n with its zone, as `--updated-since` does.\n- `pr list --updated-since <iso>` keeps every pull request that is still active, plus\n those created or closed at or after that instant. Azure DevOps records no\n last-updated time on a pull request (only `creationDate` and `closedDate`), so this\n is a superset of what changed: a sync that merges by `pullRequestId` misses nothing.\n It combines with the other filters, and `--limit` counts the pull requests it keeps.\n- `pr get <id> --include <list>` adds `data.included`, holding only the lists asked\n for (comma-separated, any case), each every page of Azure DevOps' own records:\n `reviews` (the comment threads, where each vote change is a system comment in a\n thread whose `properties.CodeReviewThreadType` is `VoteUpdate`, beside each\n reviewer's comments with `publishedDate`), `checks` (the pull request's statuses),\n `commits`, and `files` (the `changeEntries` of the latest iteration). Each list\n costs one or more extra requests; an unknown name is refused before any request.\n- `pr merge` reads the pull request for its source commit, then asks the server to\n complete it with `--strategy noFastForward` (default), `squash`, `rebase` or\n `rebaseMerge`. A pull request with no source commit yet is refused with\n `INVALID_INPUT` before anything is changed. Completion is asynchronous: check `data.status` and\n `data.mergeStatus`, which stay `active` and `queued` while policies or conflicts\n hold it.\n- `pr update` doesn't change reviewers: the API doesn't take them on that call.\n- `pr comments` flattens every live thread's comments, oldest first, each with\n `threadId` and `threadContext` (null for a general comment). System comments (votes,\n pushes) are left out unless `--include-system`. `pr threads` returns the\n threads themselves, system ones included.\n- `pr comment-inline` anchors on the right (new) side of `--line` unless\n `--line-type left`; a path without a leading `/` gets one.\n- `pr resolve` sets `--status fixed` (resolved) by default; `wontFix`,\n `closed`, `byDesign`, `pending`, or `active` to reopen.\n\n## Output, compared with `ado`\n\n`data` is the server's own JSON, so where Services and Server agree it has the same\nshape as `ado`'s, and `toil util owi map` reads `work-item get`, `work-item get-many`,\n`work-item history` and `work-item iterations` output from either area into Open Work\nItems. The differences, for anything that reads both:\n\n- **Work items** (`work-item get`, `work-item get-many`, `work-item history`,\n `work-item search`) have\n the same shape: `id`, `rev`, `fields` keyed by reference name, `relations`, `url`.\n On Services every `url` is under the organization (`https://dev.azure.com/<org>/_apis/...`)\n with no collection segment. `work-item get-many` returns `{ count, value, missing }`,\n the same as `ado`'s.\n- **Identities** (`System.AssignedTo`, `System.CreatedBy`, `createdBy`, `reviewers`)\n are the same object, `{ displayName, id, uniqueName, url, imageUrl, descriptor }`,\n but on Services `uniqueName` is the user's sign-in email, `descriptor` starts with\n `aad.` (or `msa.`), and `url` is on `vssps.dev.azure.com`. On Server `uniqueName` is\n often `DOMAIN\\user`.\n- **`work-item comments`** returns every comment, following continuation tokens;\n `ado`'s returns only the server's first page. Each comment has the same shape.\n- **`work-item create`** takes `--type`, `--title` and the other flags, and `--field`; it\n has no `--input-file` or `--parent`, which `ado`'s has.\n- **`work-item update`** takes `--field` (and `--rev`); it has no `--input-file`.\n- **`pr comments`** leaves system comments out unless `--include-system`;\n `ado`'s includes them.\n- **Ids** are whole numbers, checked by the schema: `work-item get 12abc` is refused, where\n `ado` reads it as 12.\n\n## Any endpoint: `ado-cloud api`\n\nWhen no command above covers an endpoint, `ado-cloud api` calls it directly. It sends\nthe connection's own token, the same way every other `ado-cloud` command does, to a\npath under the organization URL. Add `api-version` yourself:\n\n```bash\ntoil ado-cloud api GET _apis/projects --query api-version=7.1\ntoil ado-cloud api GET Imagile/_apis/wit/workitemtypes --query api-version=7.1 --query '$expand=states'\ntoil ado-cloud api PATCH _apis/wit/workitems/42 --query api-version=7.1 --body-file patch.json --content-type application/json-patch+json --allow-write\n```\n\n- **The path** is relative to `baseUrl`, with or without a leading `/` (in Git Bash\n on Windows, leave it off: the shell rewrites `/_apis/...` into a file path, which is\n refused). A full URL, a scheme, `//host`, a leading backslash or a `.` / `..`\n segment is refused with `INVALID_INPUT` before anything is sent, so the token never\n leaves the connection's host.\n- **The method decides the gate.** `GET` and `HEAD` are reads. `POST`, `PUT`,\n `PATCH` and `DELETE` are writes: they need `writes: true` on the connection\n **and** `--allow-write`. `DELETE` works only on the CLI: over MCP,\n `ado_cloud_api` refuses it with `INVALID_INPUT`.\n- **`--query key=value`** adds a query parameter; repeat it for more, or to repeat\n a key. **`--body-file <path>`** sends that file (inside the workspace, or `-` for\n stdin) as the body, as `application/json` unless `--content-type` says otherwise.\n A work item change is `application/json-patch+json`.\n- **Output:** a JSON body is `data`, parsed. A text body (`text/*`, XML, or no content\n type) is `data` as text. Any other body is binary: `data` is its bytes as base64,\n with an `API_BINARY` warning. Text and binary are capped at 1 MB, with an\n `API_TRUNCATED` warning when the body was longer. An empty body (a `204`, a `HEAD`)\n is `null`. `meta.response` is `{ status, contentType }`. Errors use the usual codes\n (`AUTH`, `NOT_FOUND`, `HTTP`, `NETWORK`) with Azure DevOps's own message. A body\n labelled JSON that doesn't parse comes back as text, with an `API_NOT_JSON` warning.\n- **Over MCP** it's the `ado_cloud_api` tool, with `method`, `path`, `query` (an array\n of `key=value` strings), `bodyFile`, `contentType` and `allowWrite`.\n\nPrefer a wrapped command when one exists: it knows the endpoint's paging and quirks,\nand `ado-cloud api` doesn't.\n\n## Ticket the work\n\nBefore starting work no ticket covers, rank your open work items against it.\n`work-item search` returns ids, so read them with `work-item get-many` and map that:\n\n```bash\ntoil ado-cloud work-item search --wiql \"SELECT [System.Id] FROM WorkItems WHERE [System.AssignedTo] = @Me AND [System.State] NOT IN ('Done', 'Closed', 'Removed')\"\ntoil ado-cloud work-item get-many 42 43 47 | toil util owi map | toil util owi similar --query \"Card payments time out at checkout\"\n```\n\nThen ask the person, as `core.md`, **Ticket the work**, says: attach the work to a\nmatch (nothing is written), create a sub-task under it, or create a new ticket.\n`work-item create` takes no parent here, so a sub-task is created with\n`toil ado-cloud work-item create --type Task --title \"<text>\" --allow-write` and\nlinked to its parent on the board. A new ticket takes the project from the dossier.\nBoth are writes, made only on the person's yes.\n\n## Notes\n\n- `toil connections test` reads the organization's connection data, which names the\n token's own user.\n- A 429 is retried after the delay Azure DevOps asks for, as in every area.\n- Not covered yet: pipelines and builds, attachments, work item types and fields,\n areas, links, tags, team capacity and settings changes, and PR files and diffs.\n `ado-cloud api` reaches all of them.\n",
140421
+ "ado.md": '---\narea: ado\ndescription: Work items, git repositories, pull requests and pipelines on Azure DevOps Server\n---\n\n# Azure DevOps Server (`ado`)\n\nWork items, git repositories, pull requests and pipelines on **Azure DevOps Server**\n(on-premises), through its REST API with `api-version=7.1`. Verification level:\n`unit`.\n\n**Supported versions:** Azure DevOps Server 2022.1 or later (REST API 7.1). Requests\nsend `api-version=7.1` (`7.1-preview.1` for connection data, `7.1-preview.4` for work\nitem comments), which newer servers also accept. Azure DevOps Server 2022 RTM, 2020\nand 2019 are out of scope: an older server\'s "REST API version out of range" answer\ncomes back as an error saying the server is too old for toil and naming 2022.1.\n\n## Credential\n\nAn Azure DevOps **personal access token**: in Azure DevOps, User settings \u2192 Personal\naccess tokens \u2192 New Token. Give it the scopes the commands you\'ll use need (Work\nItems, Code, Build; Read & write for the write commands). toil sends it as\n`Authorization: Basic base64(":" + token)`, with an empty user name. There is no\npassword or browser login.\n\nIn an Azure Pipelines job, the job\'s own token, `SYSTEM_ACCESSTOKEN`, is read when\n`TOIL_ADO_PAT` isn\'t set (for the default connection, and before anything in the\nconfig file), so a pipeline step needs only `TOIL_ADO_BASE_URL`. Map it into the\nstep\'s environment (`env: SYSTEM_ACCESSTOKEN: $(System.AccessToken)`).\n\n## Configuration\n\n| Key | Env var | Required | Meaning |\n|-----|---------|----------|---------|\n| `baseUrl` | `TOIL_ADO_BASE_URL` | yes | Server root, e.g. `https://ado.imagile.dev` (keep any context path, such as `/tfs`) |\n| `pat` | `TOIL_ADO_PAT` (or `SYSTEM_ACCESSTOKEN`) | yes | Personal access token |\n| `collection` | `TOIL_ADO_COLLECTION` | no | Default collection, when `--collection` isn\'t given |\n| `project` | `TOIL_ADO_PROJECT` | no | Default team project, when `--project` isn\'t given |\n| `repo` | `TOIL_ADO_REPO` | no | Default git repository, when `--repo` isn\'t given |\n| `fieldAliases` | `TOIL_ADO_FIELD_ALIASES` | no | Work item field aliases as a JSON object, friendly name to reference name, e.g. `{"storypoints": "Microsoft.VSTS.Scheduling.StoryPoints"}` |\n| `discoveredFields` | `TOIL_ADO_DISCOVERED_FIELDS` | no | Fields an earlier discovery recorded; kept, not read |\n| `discoveredTypes` | `TOIL_ADO_DISCOVERED_TYPES` | no | Work item types an earlier discovery recorded; kept, not read |\n| `writes` | `TOIL_ADO_WRITES` | no | `true` lets write commands run (with `--allow-write`) |\n\nEnvironment variables (CI, or a one-off shell):\n\n```bash\nexport TOIL_ADO_BASE_URL=https://ado.imagile.dev\nexport TOIL_ADO_PAT=<your personal access token>\n```\n\nOr `~/.toil/config.json`, with `collection`, `project` and `repo` usually set once\nunder `defaults.ado`:\n\n```json\n{\n "version": 2,\n "connections": {\n "corp-ado": { "area": "ado", "baseUrl": "https://ado.imagile.dev", "writes": true }\n },\n "defaults": { "ado": { "connection": "corp-ado", "collection": "DefaultCollection", "project": "Imagile", "repo": "imagile-api" } }\n}\n```\n\nThe token never goes in this file; a plaintext one there is refused with\n`CONFIG_INVALID`. Run `toil connections add corp-ado --area ado` (or\n`toil connections login corp-ado` for an existing connection) to keep it in the OS\ncredential store, or set `TOIL_ADO_PAT`.\n\n## Where a command acts\n\n`--collection <name>` (or its alias `--organization <name>`), `--project <name>` and\n`--repo <name>` are group flags, accepted before or after the command\n(`toil ado --project Imagile work-item get 42`). Without them, toil reads them from\nthe first of the workspace\'s remotes on the connection\'s host, of any name, trying\n`origin` first\n(`https://<host>[/tfs]/<collection>/<project>/_git/<repo>`, or the `_ssh` forms with\n`ssh://git@<host>` or `git@<host>:`), then the connection\'s `collection`, `project`\nand `repo` settings. `--collection` beats `--organization`, which beats the remote and\nthe settings. An `ssh://` remote with no user, an HTTPS remote with a user name, and\nthe short `<collection>/_git/<project>` form aren\'t read correctly. `meta.context`\nsays where each came from.\n\n**Every command needs a collection and a project**, even the ones that don\'t use\nthem (`whoami`, `collection list`), and fails with "Could not determine Azure\nDevOps collection" (or project) when either is missing. Every `repo` and `pr` command\nexcept `repo list` and `repo create` also needs a repo.\n\nIds are read as whole numbers from the start of the text: `12abc` is 12, and `abc` is\nsent as `NaN`.\n\n## Commands\n\nCommands are `toil ado <resource> <action> [ids...] [--flags]`. Ids are positional:\nthe resource\'s id first, then a sub-item\'s (attachment, thread, comment).\n\nServer and projects:\n\n- `whoami`, `connection-data`: The collection\'s connection data: the authenticated\n user (`authenticatedUser.id` is the identity id the vote commands use), the instance\n and the deployment. The two return the same thing.\n- `collection list`: The server\'s project collections.\n- `project list`: Every team project in the collection.\n- `project get <name>`: One team project by name.\n\nWork items (`<id>` is the work item id):\n\n- `work-item get <id>`: A work item with every field and relation.\n- `work-item create`: Create one (`--type`, `--title`, `--description`, `--assignee`,\n `--priority`, `--field name=value` repeatable, `--input-file`). `--parent <id>`\n adds a parent link afterwards; the result is the item as created, and a failed link\n is only an `ADO_PARENT_LINK_FAILED` warning, with the item already created.\n- `work-item update <id>`: Set fields (`--field name=value` repeatable, or\n `--input-file`).\n- `work-item transition <id>`: Set `--state`, or `--to <intent-or-status>` (`start`,\n `review`, `done`, `reopen` or a state name), resolved against the states the item\'s\n own type has (`core.md`, **Moving work items by intent**).\n- `work-item assign <id>`: Assign to `--assignee`, a display name or email.\n- `work-item link <id>`: Link it to `--target <id>`, `--type related` (default),\n `parent`, `child`, `duplicate`, `duplicate-of`, or a raw relation name.\n- `work-item search`: Run `--wiql`; returns the matching ids and urls, not their\n fields. `--updated-since <iso>` keeps only items changed at or after that instant: a\n date (`2026-10-01`, UTC midnight) or a date-time with its zone\n (`2026-10-01T09:00:00Z`). toil ANDs `[System.ChangedDate] >= \'<instant>\'` onto the\n query\'s own `WHERE`, in parentheses so an `OR` keeps its meaning, and asks the\n server for time precision. Time precision applies to the whole query, so with\n `--updated-since` an `=` on a date field (`[System.CreatedDate] = @Today`) matches\n one exact instant, not a day; write date conditions with `>=` and `<` instead.\n It and `--limit` work on flat queries (`FROM WorkItems`) only; a link query is\n refused. With `--limit`, each page runs the query again, so an item changed in\n between can move. A query returns at most 20,000 items, so a page can\'t end past\n that.\n- `work-item get-many <id...>`: Several work items through the batch endpoint, 200 ids\n per request, at most 1,000 per call. Returns `{ count, value, missing }`: `value`\n holds the items found in the order asked, with every field and relation, or only\n `--fields System.Title,System.State`; `missing` lists each id that doesn\'t exist or\n the token can\'t see, with an `ADO_WORK_ITEMS_MISSING` warning.\n- `work-item history <id>`: Every revision of a work item, oldest first; each is the\n whole item as it stood after that change, so neighbours show what changed and when.\n- `work-item comments <id>`, `work-item comment <id>` (`--body`): Comments; listing\n reads the first page only.\n- `work-item tag <id>`, `work-item untag <id>`: `--tags a;b` or `a,b`, matched\n ignoring case. The tag list is read and written back, with no revision check.\n- `work-item attachments <id>`: The attached files (id, name, url, size, dates).\n- `work-item attach <id>`: Upload `--file` (a path in the workspace), then link it\n (`--comment` optional). Returns the uploaded attachment\'s `{ id, url }`. If the link\n fails, the upload stays on the server.\n- `work-item download <id> <attachment-id>`: Save the attachment to `--dir` (default\n `.toil`) in the workspace; returns `{ saved, name, size }`. It never overwrites a\n file. A name Windows would read as another file is saved as one it won\'t: a device\n name such as `CON` gets a leading `_`, a `:` and what follows it is dropped, as are\n trailing dots and spaces. The token only goes to the configured host: an attachment URL naming another\n host is fetched from the configured one, with an `ADO_ATTACHMENT_HOST` warning.\n- `work-item areas`, `work-item iterations`: The area or iteration tree, `--depth`\n (default 10).\n- `work-item types`: The work item types with their states and required fields.\n- `work-item states`: The states of `--type`.\n- `work-item fields`: The collection\'s fields, or with `--type` a type\'s (those have\n no `type` or `readOnly`); `--custom-only` drops `System.*` and `Microsoft.VSTS.*`.\n- `work-item schema`: The `--input-file` JSON schema and an example; `--example-only`\n returns just the example as `data`. Needs no connection.\n\n`work-item types` and `work-item fields` have no `--save`; passing it is an unknown\noption. The aliases `--save` would store are the built-in ones below, which apply\nanyway. `--discover` is accepted and changes nothing.\n\nField names in `--field` and `--input-file` resolve through the connection\'s\n`fieldAliases`, then the built-in aliases (`title`, `state`, `description`,\n`priority`, `storypoints`, `acceptancecriteria`, `reprosteps` and others), matched\nignoring case, spaces and dashes; anything else is sent as a reference name\n(`MyOrg.Team`). To add your own alias, set `fieldAliases` as a JSON object:\n`toil connections add <name> --area ado` asks for it when setting up a connection;\non one that exists, add `"fieldAliases": { "effortdays": "MyOrg.EffortDays" }` to it\nin `~/.toil/config.json`, or set `TOIL_ADO_FIELD_ALIASES` (or\n`TOIL_CONN_<NAME>_FIELD_ALIASES`) to the JSON. An `--input-file` is\n`{ "type": "Bug", "fields": { "Title": "...", "Description": "@desc.html" } }`: a value\nstarting with `@` is read from that file. Flags win over the file, with an\n`ADO_INPUT_OVERRIDDEN` warning naming the keys.\n\nRepositories:\n\n- `repo list`, `repo create` (`--name`), `repo get`: Repositories in the project.\n- `repo default-reviewers`: Required reviewers policies covering the repository.\n- `commit status <commit>`: Statuses posted to a commit.\n\nPull requests (`<id>` is the pull request id):\n\n- `pr list`: Every pull request, `--state active` (default), `abandoned`,\n `completed` or `all`. `--creator` and `--reviewer` are sent as identity id filters,\n so pass an id (from `whoami`), not an alias. `--created-after` and\n `--created-before` take ISO 8601 dates; a date alone is UTC midnight, a date-time\n without a zone is local time. `--updated-since <iso>` (the same date forms) keeps\n every pull request that is still active, plus those created or closed at or after\n that instant. Azure DevOps records no last-updated time on a pull request (only\n `creationDate` and `closedDate`), so this is a superset of what changed: a sync\n that merges by `pullRequestId` misses nothing. It combines with the other filters,\n and `--limit` counts the pull requests it keeps.\n- `pr get <id>`: One pull request. `--include <list>` adds `data.included`, holding\n only the lists asked for (comma-separated, any case), each every page of Azure\n DevOps\' own records: `reviews` (the comment threads, where each vote change is a\n system comment in a thread whose `properties.CodeReviewThreadType` is `VoteUpdate`,\n beside each reviewer\'s comments with `publishedDate`), `checks` (the pull request\'s\n statuses), `commits`, and `files` (the `changeEntries` of the latest iteration).\n Each list costs one or more extra requests; an unknown name is refused before any\n request.\n- `pr create`: `--title`, `--source`, `--target` (default `main`), `--description`,\n `--reviewers <id,id>` (identity ids), `--draft`. Give branch names without\n `refs/heads/`, which toil adds (a full ref gets it twice).\n- `pr update <id>`: `--title`, `--description`, `--reviewers`, `--draft true|false`,\n in one PATCH.\n- `pr merge <id>`: Ask the server to complete it, `--strategy noFastForward`\n (default), `squash`, `rebase` or `rebaseMerge`, `--delete-source`. Completion is\n asynchronous; check `data.status`.\n- `pr abandon <id>`: Abandon it.\n- `pr comments <id>`: Every comment of every thread, oldest first, with `threadId` and\n `threadContext` (null for a general comment); system comments included.\n `--inline-only` or `--general-only` narrows it.\n- `pr comment <id>` (`--body`), `pr comment-inline <id>` (`--file /src/a.ts`,\n `--line 12`, `--body`, `--line-type left|right`, default `right`),\n `pr reply <id> <thread-id>` (`--body`), `pr resolve <id> <thread-id>` (status\n `fixed`).\n- `pr delete-comment <id> <thread-id> <comment-id>`: Returns `{ "deleted": true }`.\n CLI only: deletes are never exposed through MCP.\n- `pr files <id>`: Changed files of the latest iteration, at most 100.\n- `pr diff <id>`: Changed files between the last merge commits, at most 100; `--path`\n keeps one file (a leading `/` is added).\n- `pr reviewers <id>`: Reviewers and their votes.\n- `pr approve <id>`, `pr unapprove <id>`, `pr wait-for-author <id>`: Vote 10, 0 or -5\n as the token\'s own user.\n- `pr builds <id>`: Builds of the pull request\'s source branch (not of its merge ref).\n\nPipelines and runs:\n\n- `pipeline list`, `pipeline get <id>`: Pipelines (build definitions).\n- `pipeline run <id>`: Queue a run of the pipeline, `--branch` (a short name gets\n `refs/heads/`), `--parameter k=v` repeatable. `--wait` polls every `--poll` seconds\n (10) for up to `--timeout` seconds (600). A result other than `succeeded` still\n returns the build, with an `ADO_BUILD_NOT_SUCCEEDED` warning, and the CLI exits 1.\n The command\'s own time limit is 11 minutes, so a longer `--timeout` also needs\n `TOIL_TIMEOUT_MS`.\n- `run list`: Runs, `--definition <id>` or `--name <pipeline>`, `--branch` (as given,\n e.g. `refs/heads/main`), `--status`, `--top` (default 50; `--top 0` lists every\n run).\n- `run get <id>`, `run cancel <id>`: One run; cancel it.\n- `run logs <id>`: The run\'s logs; with `--log-id`, that log\'s text as\n `{ "log": "..." }`.\n\nPaging: `project list`, `pipeline list`, `run list`, `pr list`, `pr builds`,\n`work-item search` and `work-item history` return the whole list by default. With\n`--limit <n>` they return at most that many and set `meta.page.nextCursor`; pass it\nback as `--cursor`, with the same `--limit`, for the next page, until it\'s `null`.\n`run list` takes `--limit` or `--top`, not both. Every list except `work-item search`\n(one request) reads page by page and stops with an `HTTP` error after 1,000 pages,\nnaming the list.\n\nWrite commands need `writes: true` on the connection and `--allow-write` on the call.\n\n```bash\ntoil ado --collection DefaultCollection --project Imagile work-item get 42\ntoil ado work-item create --type Bug --title "Login broken" --field "Story Points=3" --allow-write\ntoil ado work-item link 42 --target 7 --type child --allow-write\ntoil ado --repo imagile-api pr list --state all\ntoil ado --repo imagile-api pr list --state all --updated-since 2026-10-01T00:00:00Z --limit 100\ntoil ado --repo imagile-api pr get 42 --include reviews,checks,commits,files\ntoil ado pr comment-inline 42 --file /src/app.ts --line 12 --body "Off by one?" --allow-write\ntoil ado work-item search --wiql "SELECT [System.Id] FROM WorkItems" --updated-since 2026-10-01 --limit 200\ntoil ado work-item get-many 42 7 --fields System.Title,System.State\ntoil ado pipeline run 5 --branch main --wait --allow-write\ntoil ado run logs 101 --log-id 3\n```\n\nOver MCP the same commands are tools named after the path, with spaces and\nhyphens as underscores (`ado_work_item_get`, `ado_pr_comment_inline`), and a\npositional id is the `id` field.\n\n## Ticket the work\n\nBefore starting work no ticket covers, rank your open work items against it.\n`work-item search` returns ids, so read them with `work-item get-many` and map that:\n\n```bash\ntoil ado work-item search --wiql "SELECT [System.Id] FROM WorkItems WHERE [System.AssignedTo] = @Me AND [System.State] NOT IN (\'Done\', \'Closed\', \'Removed\')"\ntoil ado work-item get-many 42 43 47 | toil util owi map | toil util owi similar --query "Card payments time out at checkout"\n```\n\nThen ask the person, as `core.md`, **Ticket the work**, says: attach the work to a\nmatch (nothing is written), create a sub-task under it, or create a new ticket. A\nsub-task is\n`toil ado work-item create --type Task --parent 42 --title "<text>" --allow-write`. A\nnew ticket takes the project from the dossier. Both are writes, made only on the\nperson\'s yes.\n\n## Checking a dossier\n\n`check-dossier` checks the call\'s dossier against the server: each team project it names (`project`, per repo or not, and `projects`) exists in its collection, and each repository (`repo`) in its project. The collection is the section\'s `collection`, else `--collection` or the connection\'s; a value with no collection anywhere is `INVALID_INPUT`. It\'s `toil ado check-dossier` (`--dossier <name|file>`, or the dossier the folder resolves to), and it returns `{ dossier, connection, env, ok, checked, checks, unchecked }`, one check per value with its key path. The CLI exits 1 when one is missing. A failure other than not-found (a bad token, an unreachable host) fails the command. Read only.\n',
140319
140422
  "alation.md": '---\narea: alation\ndescription: Data sources, schemas, tables, columns, catalog search and Document Hub folders and documents on Alation\n---\n\n# Alation (`alation`)\n\nThe **Alation** data catalog (data sources, schemas, tables, columns and full-text\nsearch) and its **Document Hubs** (folders and documents), through the Integration\nAPI under `/integration/v1` and `/integration/v2`. Document `create` and `update`\nwrite; everything else reads. Verification level: `unit`.\n\n**Supported versions:** The oldest Alation version toil supports hasn\'t been established. toil needs\nthe token APIs under `integration/v1` and the Document Hub endpoints under\n`integration/v2` (document, folder); releases with only Articles lack the latter. No\nrelease has been verified yet.\n\n## Credential\n\nAn Alation **refresh token** and the **numeric user ID** it belongs to: in Alation,\nyour profile \u2192 Account Settings \u2192 Authentication \u2192 Create Refresh Token. Alation shows the\nuser ID with the token. Refresh tokens last 60 days by default.\n\ntoil never sends the refresh token to the data API. It POSTs it, with the user ID, to\n`integration/v1/createAPIAccessToken/` on the connection\'s own host, and sends the\n24-hour API access token it gets back as the `TOKEN` header. The access token is kept\nin memory only, per connection, and renewed a minute before it expires; under\n`toil mcp` one exchange serves every call until then. There is no username, password\nor browser login.\n\n## Configuration\n\n| Key | Env var | Required | Meaning |\n|-----|---------|----------|---------|\n| `baseUrl` | `TOIL_ALATION_BASE_URL` | yes | Alation instance root, e.g. `https://alation.imagile.dev` (keep any context path) |\n| `refreshToken` | `TOIL_ALATION_REFRESH_TOKEN` | yes | Refresh token |\n| `userId` | `TOIL_ALATION_USER_ID` | yes | Numeric ID of the token\'s user; a number or a string of digits, anything else is `CONFIG_INVALID` |\n| `writes` | `TOIL_ALATION_WRITES` | no | `true` lets `document create` and `document update` run (with `--allow-write`) |\n\nEnvironment variables (CI, or a one-off shell):\n\n```bash\nexport TOIL_ALATION_BASE_URL=https://alation.imagile.dev\nexport TOIL_ALATION_REFRESH_TOKEN=<your refresh token>\nexport TOIL_ALATION_USER_ID=102\n```\n\nOr `~/.toil/config.json`:\n\n```json\n{\n "version": 2,\n "connections": {\n "corp-alation": { "area": "alation", "baseUrl": "https://alation.imagile.dev", "userId": 102 }\n },\n "defaults": { "alation": { "connection": "corp-alation" } }\n}\n```\n\nThe refresh token never goes in this file; a plaintext one there is refused with\n`CONFIG_INVALID`. Run `toil connections add corp-alation --area alation` (or\n`toil connections login corp-alation` for an existing connection) to keep it in the\nOS credential store, or set `TOIL_ALATION_REFRESH_TOKEN`. There\'s no CI fallback\nvariable.\n\nA refused exchange is `AUTH`, naming the endpoint: check the refresh token and user ID,\nor make a new refresh token if it\'s past its 60 days. Alation\'s paths are Django\nroutes, so every path keeps its trailing slash. A redirect to another host is refused,\nso the token stays on the configured one.\n\n## Commands\n\nIDs are positional and must be positive integers. Lists return one page: `--limit`\n(default 100, 1 to 1000) and `--offset` (default 0, sent to Alation as `skip`), as\n`{ count, limit, skip, <items> }`.\n\n- `token status`: Mint an API access token from the configured refresh token and\n report its expiry (verifies credentials). It mints a new token each time, then\n validates it, and returns `user_id`, `created_at`, `token_expires_at` and\n `token_status`, never the token.\n- `datasource list`: List data sources (`--include-undeployed`, `--include-hidden`),\n as `{ count, datasources }`; not paged.\n- `datasource get`: Get a data source by ID.\n- `schema list`: List schemas, optionally within one data source (`--ds`, `--name`).\n- `schema get`: Get a schema by ID.\n- `table list`: List tables (descriptions, custom fields, fully-qualified keys):\n `--ds`, `--schema`, `--schema-name`, `--name`, and `--search` for a\n case-insensitive substring of the name.\n- `table get`: Get a table by ID, optionally with its columns. `--columns` adds\n `columnCount` and `columns`, the first 1000 by ID, with an\n `ALATION_COLUMNS_TRUNCATED` warning when it reaches 1000.\n- `column list`: List columns of a table (types, descriptions, keys, custom fields):\n `--table`, `--table-name`, `--schema`, `--ds`, `--name`, `--search`. At least one\n filter is required.\n- `column get`: Get a column by ID.\n- `search`: Full-text search across the catalog. `--otype table,column` restricts\n the object types (checked against Alation\'s list), `--limit` (default 20, at most\n 10000) and `--offset` page it. Returns `{ query, total, limit, offset,\n fullSearchUrl, results }`.\n- `folder list`: List folders in a Document Hub (`--hub`, `--parent`, `--search`).\n- `folder get`: Get a Document Hub folder by ID.\n- `document list`: List documents in a Document Hub or folder (`--hub`, `--folder`,\n `--parent-document`, `--search`, `--deleted`).\n- `document get`: Get a document by ID, including its custom field values.\n- `document schema`: Print the `--input-file` JSON schema and an example for\n document create/update. With `--example-only`, `data` is the example itself, ready\n to save as an input file. It needs no connection.\n- `document create`: Create a document (async: returns a job ID; check it with\n `alation job get`). Needs a title, `--hub` and `--folder`, from flags or\n `--input-file`.\n- `document update`: Update a document (async: returns a job ID; custom field values\n replace existing values per field). It can\'t change hubs, and needs at least one\n change.\n- `job get`: Get the status of a bulk job (returned by document create/update).\n\n`get` commands read the list endpoint with `id=<n>&limit=1`. If no row has that ID\nthey return the first row anyway, with an `ALATION_ID_MISMATCH` warning in\n`meta.warnings`; check `data.id`.\n\n### Document input files\n\n`--input-file <path>` (`-` reads stdin on the CLI) holds `title`, `description`,\n`hub`, `folder`, `template`, `parentDocument`, `navLinkFolders`, and `fields`: custom\nfield values keyed by numeric field ID. Custom fields need a template. A string value\nstarting with `@` is read from that file, inside the workspace. Flags win over the\nfile, and a `meta.warnings` entry names each value they overrode. Create and update\nreturn `{ jobId, document, overrides? }`, where `document` is the payload sent.\n\n```bash\ntoil alation search customer --otype table,column\ntoil alation table get 7 --columns\ntoil alation document schema --example-only > doc.json\ntoil alation document create --input-file doc.json --allow-write\ntoil alation job get 555\n```\n',
140320
140423
  "artifactory.md": '---\narea: artifactory\ndescription: Repositories, artifact metadata and properties, AQL search, builds, and dependency versions and licenses on JFrog Artifactory\n---\n\n# JFrog Artifactory (`artifactory`)\n\nRepositories, artifact metadata and properties, AQL search, Build Integration, and\nnewer versions and licenses for a dependency inventory, on **JFrog Artifactory**,\nthrough its classic REST API (`api/...`). `artifact set-properties` is the one command that\nwrites. Verification level: `unit`.\n\n**Supported versions:** The oldest JFrog Artifactory version toil supports hasn\'t been established. toil\ncalls the classic REST API (`api/...`) and AQL with an access or identity token sent\nas a Bearer header. No release has been verified yet.\n\n## Credential\n\nAn Artifactory **access token** or **identity token**: in Artifactory, your profile \u2192\nEdit Profile \u2192 Generate an Identity Token. toil sends it as\n`Authorization: Bearer <token>`. There is no username, password or browser login, and\nno CI fallback variable.\n\n## Configuration\n\n| Key | Env var | Required | Meaning |\n|-----|---------|----------|---------|\n| `baseUrl` | `TOIL_ARTIFACTORY_BASE_URL` | yes | Artifactory root, keeping any context path, e.g. `https://artifactory.imagile.dev/artifactory` |\n| `token` | `TOIL_ARTIFACTORY_TOKEN` | yes | Access or identity token |\n| `npmRepo` | `TOIL_ARTIFACTORY_NPM_REPO` | no | npm repository key for `package outdated` and `package license-check` |\n| `nugetRepo` | `TOIL_ARTIFACTORY_NUGET_REPO` | no | NuGet repository key for `package outdated` and `package license-check` |\n| `mavenRepo` | `TOIL_ARTIFACTORY_MAVEN_REPO` | no | Maven repository key for `package outdated` |\n| `writes` | `TOIL_ARTIFACTORY_WRITES` | no | `true` lets `artifact set-properties` run (with `--allow-write`) |\n\nEnvironment variables (CI, or a one-off shell):\n\n```bash\nexport TOIL_ARTIFACTORY_BASE_URL=https://artifactory.imagile.dev/artifactory\nexport TOIL_ARTIFACTORY_TOKEN=<your access token>\nexport TOIL_ARTIFACTORY_NPM_REPO=npm-remote\n```\n\nOr `~/.toil/config.json`:\n\n```json\n{\n "version": 2,\n "connections": {\n "corp-artifactory": { "area": "artifactory", "baseUrl": "https://artifactory.imagile.dev/artifactory", "npmRepo": "npm-remote", "nugetRepo": "nuget-remote", "mavenRepo": "maven-remote" }\n },\n "defaults": { "artifactory": { "connection": "corp-artifactory" } }\n}\n```\n\nThe token never goes in this file; a plaintext one there is refused with\n`CONFIG_INVALID`. Run `toil connections add corp-artifactory --area artifactory` (or\n`toil connections login corp-artifactory`) to keep it in the OS credential store, or\nset `TOIL_ARTIFACTORY_TOKEN`.\n\n## Commands\n\n- `ping`: Check Artifactory connectivity and authentication. `data` is Artifactory\'s\n text answer, normally `OK`.\n- `repo list`: List repositories (`--type local|virtual|remote|federated`,\n `--package-type npm|maven|nuget|docker|pypi|...`).\n- `artifact get <repo> <path>`: Get metadata for an artifact or folder (checksums,\n size, timestamps).\n- `artifact properties <repo> <path>`: Read custom properties on an artifact.\n- `artifact set-properties <repo> <path> key=value...`: Set custom properties on an artifact. A\n write: needs `writes: true` on the connection and `--allow-write`. Without\n `--recursive` no `recursive` parameter is sent, so on a folder Artifactory\'s own\n default applies. Values are sent as typed: a comma makes several values, and a `;`\n starts another property. `data` is `{ repo, path, properties }` as asked for.\n- `artifact search`: Search artifacts using AQL, newest first. Needs at least one of `--repo`,\n `--name` or `--path` (`*` and `?` wildcards); `--after` / `--before` filter on the\n creation date (ISO 8601); `--limit` defaults to 100 (0 also means 100);\n `--properties` asks for properties too. `data` is `{ results, range }`.\n- `build list`: List builds registered in Artifactory Build Integration, each with a\n `name` derived from its `uri`, and a `hint` when there are none. `--timeout <s>`\n (default 60) is the request\'s timeout; the command itself allows up to 600 s.\n- `build runs <name>`: List all run numbers for a build.\n- `build get <name> <number>`: Get build info (artifacts, dependencies, VCS revision)\n for a specific run.\n- `package outdated` (also `toil deps outdated`): Check for newer versions available in\n Artifactory, for the direct production dependencies of an inventory.\n `--ecosystem npm|nuget|maven|all` (default `all`); `--major`, `--minor` or `--patch`\n keep only bumps of at least that size. Ecosystems with no repository key set are\n listed in `uncheckedEcosystems`.\n- `package license-check` (also `toil deps license-check`): Report licenses for the direct\n dependencies of an inventory (`--ecosystem`, `--include-dev`). Maven licenses are\n always `null`; a NuGet package with only a license URL reports `See licenseUrl`.\n\n`package outdated` and `package license-check` read the inventory that `toil deps scan` writes, from\n`--from <file>` or, when that\'s left out on the CLI, from stdin; over MCP, pass `from`.\nThey first ping Artifactory and stop if it doesn\'t answer or rejects the token, then\nmake one request per package, one at a time, so they\'re allowed up to 600 s. A lookup\nthat fails for any reason (a wrong repository key included) counts as no answer: the\npackage is left out of `outdated`, or gets `license: null`.\n\n```bash\ntoil artifactory artifact search --repo libs-release-local --name \'api-*.jar\' --limit 10\ntoil artifactory artifact set-properties libs-release-local dev/imagile/api/1.4.0/api-1.4.0.jar qa.status=passed --allow-write\ntoil deps scan | toil artifactory package outdated --ecosystem npm --minor\ntoil artifactory package license-check --from inventory.json --include-dev\n```\n',
140321
140424
  "bitbucket-cloud.md": '---\narea: bitbucket-cloud\ndescription: Repositories, branches, tags, commits, diffs, files, pull requests, comments, build statuses and Pipelines on Bitbucket Cloud\n---\n\n# Bitbucket Cloud (`bitbucket-cloud`)\n\nRepositories, branches and tags, commits, diffs, files, pull requests, comments,\nbuild statuses and Pipelines on **Bitbucket Cloud** (`https://api.bitbucket.org/2.0`,\nREST API 2.0). Built from Atlassian\'s API documentation and never run against a live\nworkspace. Verification level: `unit`.\n\nFor Bitbucket Data Center or Server, use the `bitbucket` area instead. The two are\nseparate areas because their APIs differ: Cloud has workspaces where Data Center has\nprojects, identifies people by Atlassian account id rather than username, keeps no\npull request version, and pages by a `next` link.\n\n**Supported versions:** The oldest Bitbucket Cloud version toil supports hasn\'t been established.\nBitbucket Cloud is always current. toil calls REST API 2.0\n(`https://api.bitbucket.org/2.0`) with an Atlassian API token sent as Basic auth with\nthe account email, or a workspace, project or repository access token sent as Bearer.\nNothing has been run against a live workspace yet.\n\n## Credential\n\nOne of two, each generated once in Atlassian\'s UI. A connection holds exactly one;\nsetting both is refused with `CONFIG_INVALID`.\n\n- **An Atlassian API token with Bitbucket scopes**, plus that account\'s **email\n address**. Create it at https://id.atlassian.com/manage-profile/security/api-tokens\n \u2192 Create API token with scopes \u2192 Bitbucket. toil sends\n `Authorization: Basic base64(<email>:<apiToken>)`, as Atlassian documents. The\n token acts as you. Scopes:\n - reads: `read:repository:bitbucket`, `read:pullrequest:bitbucket` and\n `read:pipeline:bitbucket`, plus `read:user:bitbucket` for `toil connections test`\n - writes: `write:pullrequest:bitbucket` (pull requests and comments),\n `write:repository:bitbucket` (`branch create`, `tag create`) and\n `admin:repository:bitbucket` (`repo create`)\n- **A workspace, project or repository access token**, from Repository settings,\n Project settings or Workspace settings \u2192 Access tokens. toil sends\n `Authorization: Bearer <accessToken>`. The token acts as itself, named after the\n token, on only what it was made for. Scopes: `repository`, `pullrequest` and\n `pipeline` to read; `pullrequest:write` and `repository:write` to write.\n `toil connections test` checks it against the connection\'s `workspace` and `repo`,\n and can\'t check one with neither.\n\n**App passwords no longer work** and toil doesn\'t take them. A `401`, `403` or `410`\nfrom Bitbucket Cloud is `AUTH`, and its fix names the credential to create and the\nscopes it needs. There is no OAuth app, Connect app or browser login.\n\n## Configuration\n\n| Key | Env var | Required | Meaning |\n|-----|---------|----------|---------|\n| `baseUrl` | `TOIL_BITBUCKET_CLOUD_BASE_URL` | yes | REST API root: `https://api.bitbucket.org/2.0` |\n| `email` | `TOIL_BITBUCKET_CLOUD_EMAIL` | with `apiToken` | Email address of the Atlassian account the API token belongs to |\n| `apiToken` | `TOIL_BITBUCKET_CLOUD_API_TOKEN` | one of the two | Atlassian API token with Bitbucket scopes (a secret) |\n| `accessToken` | `TOIL_BITBUCKET_CLOUD_ACCESS_TOKEN` | one of the two | Workspace, project or repository access token (a secret) |\n| `workspace` | `TOIL_BITBUCKET_CLOUD_WORKSPACE` | no | Default workspace slug, when `--ws` isn\'t given |\n| `repo` | `TOIL_BITBUCKET_CLOUD_REPO` | no | Default repository slug, when `--repo` isn\'t given |\n| `writes` | `TOIL_BITBUCKET_CLOUD_WRITES` | no | `true` lets write commands run (with `--allow-write`) |\n\n**CI fallback:** in Bitbucket Pipelines, the default connection takes `workspace` from\n`BITBUCKET_WORKSPACE` and `repo` from `BITBUCKET_REPO_SLUG`, which Pipelines sets on\nevery step, when `TOIL_BITBUCKET_CLOUD_WORKSPACE` and `TOIL_BITBUCKET_CLOUD_REPO`\naren\'t set. Pipelines sets no API credential, so the token is still yours to supply as\na secured variable.\n\n```bash\nexport TOIL_BITBUCKET_CLOUD_BASE_URL=https://api.bitbucket.org/2.0\nexport TOIL_BITBUCKET_CLOUD_EMAIL=you@example.com\nexport TOIL_BITBUCKET_CLOUD_API_TOKEN=<your API token>\n# or, instead of the two above:\nexport TOIL_BITBUCKET_CLOUD_ACCESS_TOKEN=<your access token>\n```\n\nOr `~/.toil/config.json`, with `workspace` and `repo` usually set once under\n`defaults.bitbucket-cloud`:\n\n```json\n{\n "version": 2,\n "connections": {\n "imagile-bbc": { "area": "bitbucket-cloud", "baseUrl": "https://api.bitbucket.org/2.0", "email": "you@example.com", "writes": true }\n },\n "defaults": { "bitbucket-cloud": { "connection": "imagile-bbc", "workspace": "imagile", "repo": "toil" } }\n}\n```\n\nNeither token ever goes in this file; a plaintext one there is refused with\n`CONFIG_INVALID`. Run `toil connections add imagile-bbc --area bitbucket-cloud` (or\n`toil connections login imagile-bbc`) to keep it in the OS credential store, or set\nthe env var. Env vars always win over the file.\n\n## Workspace and repository\n\nEvery command takes `--ws <slug>` and `--repo <slug>`, before or after the command\nname: `toil bitbucket-cloud --ws imagile --repo toil pr list`. It\'s `--ws`, not\n`--workspace`, because toil\'s own `--workspace` is the folder commands may read and\nwrite files in. Each falls back to a dossier, then the connection\'s `workspace` and\n`repo`. The git remote is not read. `repo list` and `repo create` need only the\nworkspace; everything else needs both. Over MCP they\'re the `workspace` and `repo`\nfields.\n\n## Commands\n\nCommands are `toil bitbucket-cloud <resource> <action> [ids...] [--flags]`; ids are\npositional. Every command also takes `--connection <name>`. Write commands (marked \u270E)\nneed `writes: true` on the connection **and** `--allow-write`. Names and flags match\n`bitbucket` wherever the operation is the same. MCP tools are\n`bitbucket_cloud_<command>` (`bitbucket_cloud_pr_get`), and a positional id is the\nfield of the same name (`id` for a pull request). `pr delete-comment` is CLI only: it\nis never an MCP tool.\n\n| Command | Flags | Returns |\n|---------|-------|---------|\n| `repo list` | `--filter --limit --cursor` | Repositories in the workspace |\n| `repo get` | | The repository |\n| `repo create` \u270E | `--name --description --project --public` | The created repository (private unless `--public`) |\n| `repo default-reviewers` | | The repository\'s default reviewers |\n| `branch list` | `--filter --limit --cursor` | Branches, each with its target commit |\n| `branch create` \u270E | `--name --commit` | The created branch |\n| `tag list` | `--filter --limit --cursor` | Tags, each with its target commit |\n| `tag create` \u270E | `--name --commit --message` | The created annotated tag |\n| `commit list` | `--branch --path --limit --cursor` | Commits, newest first (100 unless `--limit` says otherwise) |\n| `commit get <commit>` | | The commit |\n| `commit status <commit>` | | Build statuses on the commit |\n| `file get <path>` | `--ref` | `{ path, commit, content }` |\n| `file list [path]` | `--ref` | The folder\'s files and subfolders (the repository root without a path) |\n| `pr list` | `--state --query --updated-since --limit --cursor` | Pull requests in one state (`OPEN` unless `--state` says otherwise) |\n| `pr get <id>` | `--include` | The pull request, with participants, plus `included` lists on request |\n| `pr create` \u270E | `--title --source --target --description --reviewers --close-source-branch --draft` | The created pull request |\n| `pr update <id>` \u270E | `--title --description --reviewers --target` | The updated pull request |\n| `pr merge <id>` \u270E | `--strategy --message --delete-branch` | The merged pull request, or `{ pending, taskStatus }` |\n| `pr decline <id>` \u270E | | The declined pull request |\n| `pr current` | | The open pull request from the current git branch, or `null` |\n| `pr diff [id]` | `--spec --file --context-lines` | `{ diff }`, unified diff text |\n| `pr files <id>` | | Paths the pull request changes |\n| `pr approve <id>` \u270E | | The participant record |\n| `pr unapprove <id>` \u270E | | `{ unapproved }` |\n| `pr request-changes <id>` \u270E | | The participant record |\n| `pr reviewers <id>` | | Reviewer participants, with `approved` and `state` |\n| `pr builds <id>` | | Build statuses on the pull request |\n| `pr comments <id>` | `--no-with-replies --inline-only --general-only` | Comments, oldest first, replies included |\n| `pr comment <id>` \u270E | `--body` | The comment |\n| `pr comment-inline <id>` \u270E | `--file --line --body --line-type` | The comment |\n| `pr reply <id> <comment-id>` \u270E | `--body` | The reply |\n| `pr resolve <id> <comment-id>` \u270E | | The resolution record |\n| `pr delete-comment <id> <comment-id>` \u270E (CLI only) | | `{ deleted }` |\n| `pipeline list` | `--branch --limit --cursor` | Pipeline runs, newest first (100 unless `--limit` says otherwise) |\n| `pipeline get <pipeline>` | | The pipeline run |\n| `pipeline steps <pipeline>` | | Its steps |\n| `pipeline logs <pipeline> <step>` | | `{ log }`, the step\'s log text |\n\n```bash\ntoil bitbucket-cloud --ws imagile --repo toil pr list --state ALL --limit 20\ntoil bitbucket-cloud --ws imagile --repo toil pr list --updated-since 2026-10-01T09:30:00Z\ntoil bitbucket-cloud --ws imagile --repo toil pr get 42 --include reviews,checks\ntoil bitbucket-cloud --ws imagile --repo toil file get src/retry.ts --ref feature/retries\ntoil bitbucket-cloud --ws imagile --repo toil pr diff 42 --file src/retry.ts\ntoil bitbucket-cloud --ws imagile --repo toil pr create --title "Add retries" --source feature/retries --allow-write\ntoil bitbucket-cloud --ws imagile --repo toil pipeline list --branch main --limit 5\n```\n\n### People\n\nBitbucket Cloud has no usernames in its API. `--reviewers` takes a comma-separated\nlist of **Atlassian account ids** (`557058:abc12345-\u2026`), or `{uuid}`s in braces, as\n`pr get` and `repo default-reviewers` show them. `pr list --query` filters with\nBitbucket\'s query language, for example `--query \'author.account_id = "557058:abc12345"\'`\nor `--query \'source.branch.name = "feature/retries"\'`, where `bitbucket` had\n`--author` and `--reviewer`. `--updated-since` takes an ISO 8601 date (midnight UTC) or a\ndate and time with a zone, and goes to Bitbucket as `updated_on >= <instant>` in the\nsame query, after any `--query` in parentheses.\n\n### What a pull request carries\n\n`pr get <id> --include reviews,checks,commits,files` adds an `included` object\nholding only the lists named, each as Bitbucket returns it with every page read:\n`reviews` (the activity entries holding an `approval` or `changes_requested`),\n`checks` (the build statuses `pr builds` returns), `commits`, and `files` (the\ndiffstat entries, with `lines_added` and `lines_removed` for each file). Each list\ncosts more requests; an unknown name is refused before any is sent.\n\n### Paging\n\nLists follow Bitbucket\'s `next` link, 100 items a request, and toil follows a link\nonly when it\'s on the connection\'s own host and names the same list. Without\n`--limit`, `repo list`, `branch list`, `tag list` and `pr list` read every page;\n`commit list` and `pipeline list` return the newest 100, since a history has no end\nworth reaching. With `--limit N` they return at most N, and `meta.page.nextCursor`\nresumes: pass it back as `--cursor` (with `--limit` on the lists that read every page).\nEvery other list is read in full. Paging stops after 1,000 requests with an error\nnaming the list.\n\n## Any endpoint: `bitbucket-cloud api`\n\nWhen no command above covers an endpoint, `bitbucket-cloud api` calls it directly. It\nsends the connection\'s own credential, the same way every other `bitbucket-cloud`\ncommand does, to a path under the connection\'s `baseUrl` (so the path starts after\n`/2.0`):\n\n```bash\ntoil bitbucket-cloud api GET repositories/imagile/toil\ntoil bitbucket-cloud api GET repositories/imagile/toil/refs/branches --query \'q=name ~ "release"\' --query pagelen=10\ntoil bitbucket-cloud api GET repositories/imagile/toil/pullrequests/42/merge/task-status/abc12345\ntoil bitbucket-cloud api POST repositories/imagile/toil/pullrequests/42/comments --body-file comment.json --allow-write\n```\n\n- **The path** is relative to `baseUrl`, with or without a leading `/` (in Git Bash\n on Windows, leave it off: the shell rewrites `/repositories/...` into a file path,\n which is refused). A full URL, a scheme, `//host`, a leading backslash or a `.` /\n `..` segment is refused with `INVALID_INPUT` before anything is sent, so the token\n never leaves the connection\'s host.\n- **The method decides the gate.** `GET` and `HEAD` are reads. `POST`, `PUT`,\n `PATCH` and `DELETE` are writes: they need `writes: true` on the connection\n **and** `--allow-write`. `DELETE` works only on the CLI: over MCP,\n `bitbucket_cloud_api` refuses it with `INVALID_INPUT`.\n- **`--query key=value`** adds a query parameter; repeat it for more, or to repeat\n a key. **`--body-file <path>`** sends that file (inside the workspace, or `-` for\n stdin) as the body, as `application/json` unless `--content-type` says\n otherwise.\n- **Output:** a JSON body is `data`, parsed. A text body (`text/*`, XML, or no content\n type) is `data` as text. Any other body is binary: `data` is its bytes as base64,\n with an `API_BINARY` warning. Text and binary are capped at 1 MB, with an\n `API_TRUNCATED` warning when the body was longer. An empty body (a `204`, a `HEAD`)\n is `null`. `meta.response` is `{ status, contentType }`. Errors use the usual codes\n (`AUTH`, `NOT_FOUND`, `HTTP`, `NETWORK`) with Bitbucket\'s own message; a `410` here\n is `AUTH`, as it is on every other command. A body labelled JSON that doesn\'t parse comes back as text,\n with an `API_NOT_JSON` warning.\n- **Over MCP** it\'s the `bitbucket_cloud_api` tool, with `method`, `path`, `query` (an\n array of `key=value` strings), `bodyFile`, `contentType` and `allowWrite`.\n\nPrefer a wrapped command when one exists: it knows the endpoint\'s paging and quirks,\nand `bitbucket-cloud api` doesn\'t.\n\n## Notes\n\n- `file get` and `file list` read at `--ref`, a branch, tag or commit hash (the\n repository\'s main branch without it). A branch or tag is first resolved to its\n newest commit, which `data.commit` reports, so a branch name with a `/` works. A\n file comes back as text; read a folder with `file list`, not `file get`.\n- `pr diff <id>` and `pr files` read the pull request first and diff its source commit\n against its destination with `topic=true`, the three-dot diff Bitbucket shows on\n the pull request, so `--file` and `--context-lines` apply. `pr diff --spec` takes one\n commit (against its first parent) or `a..b`. Pass exactly one of an id and `--spec`.\n A pull request from a fork isn\'t diffed this way: use `--spec` in the fork, or `api`.\n- `pr update` reads the pull request first and sends back its current title,\n description and reviewers for anything not given, so nothing is cleared by\n omission. `--reviewers` replaces the whole list.\n- `pr merge --delete-branch` sends `close_source_branch`, which deletes the source\n branch after the merge. `--strategy` is one of `merge_commit`, `squash`,\n `fast_forward`, `squash_fast_forward`, `rebase_fast_forward` or `rebase_merge`; left\n out, the repository\'s default applies. When Bitbucket queues the merge or takes\n longer than it waits (`202`), `data` is `{ pending: true, taskStatus }` with a\n `BITBUCKET_CLOUD_MERGE_PENDING` warning: read `taskStatus` with\n `bitbucket-cloud api GET` until its `task_status` is `SUCCESS`.\n- `pr request-changes` is Cloud\'s needs-work. `pr unapprove` withdraws an approval.\n Adding a single reviewer is `pr update --reviewers` with the whole list.\n- `pr comment-inline` anchors `ADDED` and `CONTEXT` lines in the new file (`to`) and\n `REMOVED` lines in the old one (`from`).\n- `pr resolve` takes the thread\'s root comment; one that\'s already resolved is\n an HTTP `409`.\n- `pr current` matches the current git branch against open pull requests\' source\n branch. It reads the branch from `.git`, and the workspace and repository from\n `--ws` and `--repo` or the connection, never from the remote.\n- `pipeline logs` follows a redirect to signed storage with every header dropped, so\n the credential stays on `baseUrl`\'s host. Pipeline and step uuids are taken with or\n without their braces.\n- Not covered: Issues and Wikis (removed from Bitbucket Cloud in August 2026), the\n cross-workspace APIs (retired in April 2026), anything only a Connect app can\n reach, starting or stopping a pipeline, and deleting branches, tags or\n repositories.\n- A 429 is retried after the delay Bitbucket asks for, as in every area.\n',
@@ -140324,18 +140427,18 @@ var skillFiles = {
140324
140427
  "confluence-cloud.md": '---\narea: confluence-cloud\ndescription: Pages, spaces, CQL search, comments, labels and attachments on Confluence Cloud\n---\n\n# Confluence Cloud (`confluence-cloud`)\n\nPages, spaces, CQL search, comments, labels and attachments on **Confluence Cloud**\n(`https://<your-site>.atlassian.net`, REST API v2, with v1 where v2 has no\nendpoint). Built from Atlassian\'s API documentation and never run against a live\nsite. Verification level: `unit`.\n\nFor Confluence Data Center or Server, use the `confluence` area instead. The two are\nseparate areas because their APIs differ: Cloud\'s v2 API has different paths, pages\nby cursor rather than offset, and addresses spaces by a numeric id rather than their\nkey.\n\n**Supported versions:** The oldest Confluence Cloud version toil supports hasn\'t been established.\nConfluence Cloud is always current. toil calls REST API v2\n(`/wiki/api/v2`) and, where v2 has no endpoint, v1 (`/wiki/rest/api`: CQL search,\nadding and removing labels, attachment uploads), with an Atlassian account email and\nAPI token sent as Basic auth. Nothing has been run against a live site yet.\n\n## Credential\n\nAn **Atlassian account API token** plus that account\'s **email address**. Create\nthe token at https://id.atlassian.com/manage-profile/security/api-tokens (Atlassian\naccount \u2192 Security \u2192 API tokens \u2192 Create API token). toil sends\n`Authorization: Basic base64(<email>:<apiToken>)`, as Atlassian documents for\nscripts. There is no password, OAuth app or browser login. The token acts with the\naccount\'s own permissions, so a read sees what that account can see.\n\nThe same account token works for Jira Cloud. With no token of its own, the default\nconnection uses `TOIL_JIRA_CLOUD_API_TOKEN` (the default `jira-cloud` connection\'s env\nvalue). Any other connection borrows a `jira-cloud` connection\'s token, env or stored,\nonly by naming it: `"apiTokenFrom": "imagile-cloud"`. Its own token always wins, and\n`meta.context.shared` says when the token came from Jira Cloud. Only the token is\nborrowed: `email` is always this connection\'s own, and must be the address the token\nbelongs to.\n\n## Configuration\n\n| Key | Env var | Required | Meaning |\n|-----|---------|----------|---------|\n| `baseUrl` | `TOIL_CONFLUENCE_CLOUD_BASE_URL` | yes | Confluence Cloud site root, without `/wiki`: `https://<your-site>.atlassian.net` |\n| `email` | `TOIL_CONFLUENCE_CLOUD_EMAIL` | yes | Email address of the Atlassian account the token belongs to |\n| `apiToken` | `TOIL_CONFLUENCE_CLOUD_API_TOKEN` | yes | Atlassian account API token (a secret), unless borrowed from Jira Cloud |\n| `apiTokenFrom` | `TOIL_CONFLUENCE_CLOUD_API_TOKEN_FROM` | no | A `jira-cloud` connection whose token this connection uses |\n| `writes` | `TOIL_CONFLUENCE_CLOUD_WRITES` | no | `true` lets write commands run (with `--allow-write`) |\n\ntoil adds `/wiki/api/v2` and `/wiki/rest/api` itself, so `baseUrl` is the site root. A\n`baseUrl` ending in `/wiki` (as the browser shows it) is refused with `CONFIG_INVALID`\nbefore anything is sent: drop the `/wiki`.\nThere is no CI fallback variable. The examples use the placeholder\n`https://confluence-cloud.imagile.dev`, which never resolves; your own site is\n`https://<your-site>.atlassian.net`.\n\n```bash\nexport TOIL_CONFLUENCE_CLOUD_BASE_URL=https://confluence-cloud.imagile.dev\nexport TOIL_CONFLUENCE_CLOUD_EMAIL=you@example.com\nexport TOIL_CONFLUENCE_CLOUD_API_TOKEN=<your API token>\n```\n\nOr `~/.toil/config.json`:\n\n```json\n{\n "version": 2,\n "connections": {\n "imagile-wiki": { "area": "confluence-cloud", "baseUrl": "https://confluence-cloud.imagile.dev", "email": "you@example.com", "writes": true }\n },\n "defaults": { "confluence-cloud": { "connection": "imagile-wiki" } }\n}\n```\n\nThe token never goes in this file; a plaintext one there is refused with\n`CONFIG_INVALID`. Run `toil connections add imagile-wiki --area confluence-cloud` (or\n`toil connections login imagile-wiki`) to keep it in the OS credential store, or set\n`TOIL_CONFLUENCE_CLOUD_API_TOKEN`. Env vars always win over the file.\n\n## Commands\n\nEvery command also takes `--connection <name>`. Write commands (marked \u270E) need\n`writes: true` on the connection **and** `--allow-write`. Names and flags match\n`confluence` wherever the operation is the same. MCP tools are named\nafter the path, with spaces and hyphens as underscores (`confluence_cloud_page_get`). The two deletes are CLI\nonly: they are never MCP tools.\n\n| Command | Arguments and flags | Returns |\n|---------|-------|---------|\n| `page get` | `<id>` | The page with its storage body, plus `bodyText` |\n| `page find` | `--space <key> --title` | The page with that exact title, plus `bodyText` |\n| `page list` | `--space <key> --limit --cursor` | Pages in the space (no bodies) |\n| `page children` | `<id>` | Direct children, each with its `type` |\n| `page history` | `<id>` | Every version of the page |\n| `page search` | `--cql --limit --cursor --expand` | One page of CQL results, as Confluence returns it |\n| `page create` \u270E | `--space <key> --title --body --body-file --parent-id --representation` | The created page, plus `bodyText` |\n| `page update` \u270E | `<id> --title --body --body-file --status --representation` | The updated page, plus `bodyText` |\n| `page delete` \u270E (CLI only) | `<id>` | `{ deleted }` |\n| `page comments` | `<id>` | Top-level footer comments, each with `bodyText` |\n| `page comment` \u270E | `<id> --body --representation` | The comment, plus `bodyText` |\n| `page labels` | `<id>` | The page\'s labels |\n| `page label` \u270E | `<id> --labels <a,b>` | The labels Confluence reports |\n| `page unlabel` \u270E | `<id> --label` | `{ removed, from }` |\n| `space list` | `--type --limit --cursor` | Spaces the account can see |\n| `space get` | `<key>` | The space, with its plain-text description |\n| `page attachments` | `<page-id>` | The page\'s attachments |\n| `page attach` \u270E | `<page-id> --file --comment` | The attachments Confluence created |\n| `attachment download` | `<attachment-id> --dir` | `{ saved, filename, size }` |\n| `attachment delete` \u270E (CLI only) | `<attachment-id>` | `{ deleted }` |\n\n```bash\ntoil confluence-cloud page find --space DOCS --title "Release notes"\ntoil confluence-cloud page search --cql \'space=DOCS AND type=page AND text~"runbook"\' --limit 10\ntoil confluence-cloud page create --space DOCS --title Runbook --body-file runbook.html --parent-id 12345 --allow-write\ntoil confluence-cloud page update 12345 --title "Release notes (archived)" --allow-write\ntoil confluence-cloud attachment download att98765 --dir downloads\n```\n\n### Ids and keys\n\nPage ids are numbers (`12345`); attachment ids carry an `att` prefix (`att98765`).\nCommands that take `--space` take the space **key** (`DOCS`), as `confluence` does;\ntoil looks up the numeric space id v2 needs with one extra request, and a key that\nmatches nothing is `NOT_FOUND`. An id containing `/`, `\\`, `?` or `#` is refused with\n`INVALID_INPUT` before anything is sent, and the rest is percent-encoded as one path\nsegment.\n\n### Body format: storage\n\nBodies are **storage format**, the XHTML Confluence keeps pages in, both ways:\n\n- **Out**: every page and comment is read with `body-format=storage`, so\n `body.storage.value` is the XHTML. Beside it, `bodyText` is a plain-text rendering:\n tags dropped, blocks on their own lines, list items as `- `, table cells joined\n with ` | `, code macro text kept, macro parameters dropped. It\'s for reading, not\n for writing back.\n- **In** (`--body`, `--body-file`): storage-format XHTML, or wiki markup with\n `--representation wiki`, which Confluence converts to storage. Atlassian Document\n Format isn\'t offered.\n\n`confluence`\'s `--markdown` isn\'t here: Confluence Cloud documents no synchronous\nMarkdown converter. Write storage XHTML, or wiki markup, instead. `page get` has no\n`--expand`: v2 has no expansions, and the body always comes back.\n\n### Paging\n\nLists page by cursor. Without `--limit`, `page list` and `space list` read every\npage of results. With `--limit N` they return at most N, and `meta.page.nextCursor`\nresumes: pass it back as `--cursor` with `--limit`. Every other list\n(`page children`, `page history`, `page comments`, `page labels`,\n`page attachments`) is read in full. Paging stops after 1,000 requests with an error\nnaming the list.\n\n`page search` returns one page, as Confluence returns it (`results`, `size`, `totalSize`,\n`_links`), 25 results unless `--limit` says otherwise. When there are more,\n`meta.page.nextCursor` is the cursor from its `_links.next`: pass it as `--cursor`\n(with the same `--cql`) for the next page. `confluence`\'s `--offset` isn\'t here: Cloud\nsearch pages by cursor.\n\n## Notes\n\n- `page update` reads the page first and sends the next version number, keeping the\n title unless `--title` is given. Confluence Cloud requires a body on every update,\n so with no `--body` or `--body-file` the current storage body is sent back\n unchanged (a rename). `--status draft` sends version 1, as Atlassian documents for\n a change to draft, and deletes any draft the page already has. `--representation` without a body is `INVALID_INPUT`.\n- `page create` without `--parent-id` puts the page under the space\'s homepage, as\n the API does.\n- `page children` uses v2\'s direct children, which lists folders, whiteboards,\n databases and embeds beside child pages; each result\'s `type` says which.\n- `page history` returns the version list (`number`, `createdAt`, `authorId`,\n `message`, `minorEdit`), where `confluence` returns Data Center\'s history object.\n- `page comments` reads footer comments only, top level only: no replies and no inline\n comments. `page comment` adds a footer comment.\n- `page label` and `page unlabel` use v1, since v2 can\'t write labels. Labels are added\n with the `global` prefix. `page unlabel` sends the label as a query parameter, so any\n label can be removed.\n- `page attach` uses v1 multipart with `X-Atlassian-Token: nocheck`, and always\n adds a new attachment. The file name is the path\'s last segment, with `/` or `\\`\n splitting it on every platform.\n- `attachment download` reads the attachment, then fetches its `downloadLink` under\n `baseUrl/wiki` with the credential. Confluence answers with a redirect to a signed\n URL on Atlassian\'s media host; toil follows it with **every header dropped**, so the\n credential stays on your site. It saves under `.toil/` (or `--dir`), keeping only the\n file name, and never replaces a file that\'s already there. A name Windows would read\n as another file is saved as one it won\'t: a device name such as `CON` gets a leading\n `_`, a `:` and what follows it is dropped, as are trailing dots and spaces.\n- `page delete` and `attachment delete` move the item to the trash; neither purges.\n- A 429 is retried after the delay Confluence asks for, as in every area.\n',
140325
140428
  "confluence.md": '---\narea: confluence\ndescription: Pages, spaces, CQL search, comments, labels and attachments on Confluence Data Center\n---\n\n# Confluence Data Center (`confluence`)\n\nPages, spaces, CQL search, comments, labels and attachments on **Confluence Data\nCenter / Server** (the Server REST API under `/rest/api`). Verification level: `unit`.\n\n**Supported versions:** Confluence Data Center 7.9 or later (Server REST API). toil\nauthenticates with a personal access token, which Confluence Data Center added in 7.9.\nNo release has been verified yet.\n\n## Credential\n\nA Confluence **personal access token**: in Confluence, your profile picture \u2192 Settings \u2192\nPersonal Access Tokens \u2192 Create token. toil sends it as `Authorization: Bearer <token>`.\nThere is no username, password or browser login.\n\n**The Jira token works too.** When the default Confluence connection has no token of\nits own in env (`TOIL_CONFLUENCE_API_TOKEN`), it uses `TOIL_JIRA_API_TOKEN`, the default\nJira connection\'s env value. Any Confluence connection can instead borrow a Jira\nconnection\'s token, env or stored, by naming it: `"apiTokenFrom": "corp-jira"`.\n`meta.context.shared` says when the token came from Jira, never the value.\n\n## Configuration\n\n| Key | Env var | Required | Meaning |\n|-----|---------|----------|---------|\n| `baseUrl` | `TOIL_CONFLUENCE_BASE_URL` | yes | Confluence server root, e.g. `https://confluence.imagile.dev` (keep any context path, e.g. `https://confluence.imagile.dev/confluence`) |\n| `apiToken` | `TOIL_CONFLUENCE_API_TOKEN` | yes, unless borrowed from Jira | Personal access token |\n| `apiTokenFrom` | `TOIL_CONFLUENCE_API_TOKEN_FROM` | no | A Jira connection whose token this connection uses |\n| `writes` | `TOIL_CONFLUENCE_WRITES` | no | `true` lets write commands run (with `--allow-write`) |\n\nEnvironment variables (CI, or a one-off shell):\n\n```bash\nexport TOIL_CONFLUENCE_BASE_URL=https://confluence.imagile.dev\nexport TOIL_CONFLUENCE_API_TOKEN=<your personal access token>\n```\n\nOr `~/.toil/config.json`:\n\n```json\n{\n "version": 2,\n "connections": {\n "corp-wiki": { "area": "confluence", "baseUrl": "https://confluence.imagile.dev", "apiTokenFrom": "corp-jira" }\n }\n}\n```\n\nThe token never goes in this file; a plaintext one there is refused with\n`CONFIG_INVALID`. Run `toil connections add corp-wiki --area confluence` (or\n`toil connections login corp-wiki`) to keep it in the OS credential store, or set\n`TOIL_CONFLUENCE_API_TOKEN`. Env vars always win over the file.\n\n## Commands\n\nEvery command also takes `--connection <name>`. Write commands (marked \u270E) need\n`writes: true` on the connection **and** `--allow-write`; over MCP `allowWrite: true`\nstands in for the flag. `page delete` and `attachment delete` run on the CLI only; they are\nnot MCP tools.\n\nIds, space keys and labels go into URL paths encoded, each as one segment, so a `/`,\n`\\`, `?`, `#` or `%` in one is part of the name (label `a/b` is sent as `a%2Fb`). One\nthat is a `.` or `..` segment, bare or between slashes (`../space/DOCS`), is refused\nwith `INVALID_INPUT` before anything is sent.\n\n| Command | Arguments and flags | Returns |\n|---------|-------|---------|\n| `page get` | `<id> --expand` | The page (default expand `body.storage,version,space,ancestors`) |\n| `page find` | `--space --title` | The first page with that exact title, or `NOT_FOUND` |\n| `page list` | `--space --limit --offset` | Every page in the space (or `--limit` of them, from `--offset`) |\n| `page children` | `<id>` | Every child page |\n| `page history` | `<id>` | The page\'s history metadata |\n| `page search` | `--cql --limit --offset --expand` | Confluence\'s search result, one page (25 by default) |\n| `page create` \u270E | `--space --title --body or --body-file --markdown --parent-id --representation` | The created page |\n| `page update` \u270E | `<id> --title --body or --body-file --markdown --status --representation` | The updated page |\n| `page delete` \u270E | `<id>` | `{ deleted }` |\n| `page comments` | `<id>` | Top-level comments, with storage bodies |\n| `page comment` \u270E | `<id> --body --representation` | The comment |\n| `page labels` | `<id>` | Every label |\n| `page label` \u270E | `<id> --labels a,b` | The labels Confluence reports |\n| `page unlabel` \u270E | `<id> --label` | `{ removed, from }` |\n| `space list` | `--type --limit` | Every space (or `--limit` of them) |\n| `space get` | `<key>` | The space, with its plain-text description |\n| `page attachments` | `<id>` | Every attachment on the page |\n| `page attach` \u270E | `<id> --file --comment` | The attachments created |\n| `attachment download` | `<attachment-id> --dir` | `{ saved, filename, size }`; saves to `.toil/` by default |\n| `attachment delete` \u270E | `<attachment-id>` | `{ deleted }`; the attachment goes to the trash |\n| `check-dossier` | `--dossier <name\\|file>` (or the folder\'s dossier) | `{ dossier, connection, env, ok, checked, checks, unchecked }`: each space the dossier names (`space`, `spaces`), found or not; exit 1 when one is missing |\n\nOver MCP the same commands are tools named after the path, with spaces and hyphens\nas underscores (`confluence_page_get`, `confluence_attachment_download`), taking\ncamelCase fields named after the arguments and flags (`id`, `bodyFile`, `parentId`).\n\n## Examples\n\n```bash\ntoil confluence page get 12345\ntoil confluence page find --space DOCS --title "Release notes"\ntoil confluence page search --cql \'space=DOCS AND type=page AND text~"runbook"\' --limit 10\ntoil confluence page list --space DOCS --limit 50\ntoil confluence page create --space DOCS --title "Runbook" --body-file runbook.html --parent-id 12345 --allow-write\ntoil confluence page update 12345 --body-file runbook.html --allow-write\ntoil confluence page label 12345 --labels runbook,ops --allow-write\ntoil confluence page attach 12345 --file diagram.png --allow-write\ntoil confluence attachment download 98765 --dir downloads\n```\n\n## Notes\n\n- Bodies are Confluence **storage format** (XHTML). `--representation wiki` sends the\n value under `body.storage` with `representation: "wiki"`. `--markdown` asks\n Confluence\'s converter (`/rest/api/contentbody/convert/storage`) to turn Markdown into\n storage format first; whether your server accepts that hasn\'t been verified.\n- `--body-file -` reads the body from stdin on the CLI. Over MCP, `-` is refused because\n stdin carries the protocol; pass a file path. Files resolve inside the workspace.\n- When Confluence rejects a body, the error adds the offending line of an XML parse\n error, and known storage-format mistakes behind an HTTP 500 (`<ac:parameter name=\u2026>`,\n a macro with no `ac:macro-id`).\n- `page update` reads the current version and sends the next one, keeping the title\n unless `--title` is given. With no body it sends none.\n- `page list` and `space list` without `--limit`, and the other lists always, page\n through everything, 25 at a time. A `--limit` that isn\'t a positive whole number\n (`abc`, `0`) usually returns an empty list, with a `CONFLUENCE_LIMIT_INVALID` warning.\n- `attachment download` never replaces a file: one of the same name in the target\n directory fails with `INVALID_INPUT`. The file name is the attachment title\'s last\n path segment, made safe to save on any platform: a device name such as `CON` gets a\n leading `_`, a `:` and what follows it is dropped, as are trailing dots and spaces,\n and the characters Windows forbids become `_`. The token only ever goes to `baseUrl`\'s host: a download link naming\n another host is fetched from `baseUrl` instead, with a `CONFLUENCE_ATTACHMENT_HOST`\n warning.\n- `page attach` always creates a new attachment; a file name already on the page\n isn\'t added as a new version.\n\n## Data Center, not Cloud\n\nThis area targets Confluence Data Center and Server. Confluence Cloud is a separate\narea, `confluence-cloud`, with its own `TOIL_CONFLUENCE_CLOUD_*` settings; don\'t\npoint this one at a Cloud site.\n',
140326
140429
  "contrast.md": '---\narea: contrast\ndescription: Applications, vulnerability findings and libraries for a Contrast Security organization\n---\n\n# Contrast Security (`contrast`)\n\nApplications, vulnerability findings (traces) and libraries for one **Contrast\nSecurity** organization, through the TeamServer "ng" REST API\n(`/Contrast/api/ng/<orgUuid>/...`), on SaaS or self-hosted. Every command reads; none\nchanges anything. Verification level: `unit`.\n\n**Supported versions:** The oldest Contrast TeamServer version toil supports hasn\'t been established. toil calls the TeamServer "ng" REST API with an API key and a\nservice key. No release has been verified yet.\n\n## Credential\n\nThree values, all from **User Settings \u2192 Your Keys** in Contrast: your username, the\norganization\'s **API key** and your **service key**, plus the organization UUID shown\non the same page. toil sends two headers on every request:\n\n- `Authorization: base64(username:serviceKey)`, with no `Basic ` prefix, which is\n Contrast\'s own format\n- `API-Key: <apiKey>`\n\nThere is no password or browser login. A redirect to another host is refused, so the\nAPI key never leaves the configured instance.\n\n## Configuration\n\n| Key | Env var | Required | Meaning |\n|-----|---------|----------|---------|\n| `baseUrl` | `TOIL_CONTRAST_BASE_URL` | yes | Instance root, e.g. `https://contrast.imagile.dev` or `https://app.contrastsecurity.com` |\n| `orgUuid` | `TOIL_CONTRAST_ORG_UUID` | yes | Organization UUID |\n| `username` | `TOIL_CONTRAST_USERNAME` | yes | Contrast username |\n| `apiKey` | `TOIL_CONTRAST_API_KEY` | yes | Organization API key (secret) |\n| `serviceKey` | `TOIL_CONTRAST_SERVICE_KEY` | yes | Your service key (secret) |\n\nThere\'s no CI fallback variable.\n\nEnvironment variables (CI, or a one-off shell):\n\n```bash\nexport TOIL_CONTRAST_BASE_URL=https://contrast.imagile.dev\nexport TOIL_CONTRAST_ORG_UUID=abc12345-0000-0000-0000-000000000000\nexport TOIL_CONTRAST_USERNAME=you@example.com\nexport TOIL_CONTRAST_API_KEY=<your API key>\nexport TOIL_CONTRAST_SERVICE_KEY=<your service key>\n```\n\nOr `~/.toil/config.json`:\n\n```json\n{\n "version": 2,\n "connections": {\n "corp-contrast": {\n "area": "contrast",\n "baseUrl": "https://contrast.imagile.dev",\n "orgUuid": "abc12345-0000-0000-0000-000000000000",\n "username": "you@example.com"\n }\n },\n "defaults": { "contrast": { "connection": "corp-contrast" } }\n}\n```\n\n`apiKey` and `serviceKey` never go in this file; a plaintext one there is refused with\n`CONFIG_INVALID`. Run `toil connections add corp-contrast --area contrast` (or\n`toil connections login corp-contrast` for an existing connection) to keep them in the\nOS credential store, or set the env vars.\n\n## Commands\n\n`data` is Contrast\'s own response, as it came, except for `library get`.\n\n- `app list`: List applications in the organization.\n- `app findings <app>`: List vulnerability findings for an application.\n `--severity` and `--status` are sent as `severities` and `statuses`, as typed; a\n comma list such as `HIGH,CRITICAL` keeps its commas.\n- `finding get <app> <trace>`: Get details for a specific vulnerability finding.\n- `app libraries <app>`: List libraries used by an application, as shown on the\n Libraries tab.\n- `library get <app> <hash>`: Get details for a specific library used by an\n application, by hash. It reads the application\'s libraries 25 at a\n time until one\'s `hash` matches exactly, or a page has fewer than 25, and returns\n that one library object. No match is `NOT_FOUND`. It stops with an error after\n 1,000 pages.\n\n`app list`, `app findings` and `app libraries` take `--limit` (default 25) and\n`--offset` (default 0), sent to the server as given; they return one page, and you\npage by hand. The application ID, the trace ID and the org UUID are each encoded as one URL path segment, so a `/`, `?`, `#` or `%` in one is part of that ID.\n\nOver MCP the same commands are tools named after the path, with spaces as\nunderscores (`contrast_app_findings`, `contrast_library_get`), taking the fields\n`app`, `trace`, `hash`, `limit` and `offset`.\n\n```bash\ntoil contrast app list --limit 50\ntoil contrast app findings abc12345-0000-0000-0000-000000000000 --severity HIGH,CRITICAL\ntoil contrast library get abc12345-0000-0000-0000-000000000000 0f1e2d3c4b5a69788796a5b4c3d2e1f00f1e2d3c\n```\n',
140327
- "core.md": "---\ndescription: What every toil command shares, in detail - the envelope and errors, the contract version, --select, big results (--summary-file and --output-format toon), toil wait, paging and progress, writes and their exceptions, global flags, files and the workspace, configuration, the raw API passthrough, dossiers, the audit log, using toil from a program (@imagile-dev/toil/api), sending feedback, certificates and proxies\n---\n\n# Using toil\n\n`SKILL.md` has the rules every call needs. This page has the detail behind them, for\nwhen a call needs more than a command's own flags.\n\nThe jira, jira-cloud, ado and ado-cloud commands are `toil <area> <resource> <action>\n[ids...]`: ids are positional, everything else is a flag, and `toil <area> <resource>\n--help` lists what a resource can do (`toil jira issue --help`).\n\n## The envelope and errors\n\nEvery command prints one JSON envelope on stdout: `{ ok, data, error, meta }`.\nCheck `ok`; on failure, `error.code` says what kind of failure it was and `error.fix`\nsays what to do about it. New codes may appear in any release, so treat a code you\ndon't know as a generic failure. `meta.warnings` lists anything worth knowing that\nisn't a failure, such as a truncated result. `meta.context` says which connection a\ncall used and how it was chosen, and where any project, repo or environment it\nresolved came from. `meta.lint`, on the `db` commands that run SQL you wrote, names\nthe engine whose dialect toil checked it against and the rules that ran (`db.md`,\n**Pre-flight lint**). `--pretty` formats the output for people.\n\n`meta.contractVersion` (also in `toil version`) is the version of toil's command\ncontract: its commands, flags, `data` fields, envelope and error codes. It goes up only\nwith a breaking change, so a script or program built against one version works with\nevery toil that reports it.\n\n## Paging\n\nPaged results put the next page's cursor in `meta.page.nextCursor` (null on the last\npage) and the page size in `meta.page.limit`. Pass the cursor back with the\ncommand's own paging flag, which its reference names.\n\n## Moving work items by intent\n\n`jira issue transition`, `jira-cloud issue transition`, `ado work-item transition` and\n`ado-cloud work-item transition` take `--to <intent>` (`to` over MCP): `start`,\n`review`, `done`, `reopen`, or a status name. toil resolves it against the moves that\none item offers right now, by its own workflow, because a workflow belongs to the issue\nor work item type: a Story may go through In Review while a Task goes straight to Done.\nIn order, the first that gives exactly one move wins:\n\n1. **The dossier's pin** for the item's type: `\"transitions\": { \"Story\": { \"review\":\n \"Peer Review\" } }` in the area's section (**Dossiers**, below).\n2. **An exact name**: a transition or status called what you passed, ignoring case.\n3. **The intent's status category**: Jira's To Do, In Progress and Done categories\n serve `reopen`, `start` and `done`, and Jira files review under In Progress, so a\n status there whose name says review (In Review, Code Review) serves `review`; Azure DevOps'\n Proposed, InProgress, Resolved and Completed serve `reopen`, `start`, `review` and\n `done`. When several moves share the category, a name that starts a word with the\n intent (`Submit for Review`) picks one.\n4. **A name that says it**: the one move whose name or target status starts a word with\n the intent.\n\nIt never guesses. No match, more than one, or an item already where the intent leads is\n`INVALID_INPUT`, and the fix lists every move the item offers, by name, target status,\ncategory and id. On success `meta.transition` says what was resolved: `{ intent,\ntransition, toStatus, resolvedBy }`, `resolvedBy` being `dossier`, `status`,\n`category` or `name`. Resolving only reads (Jira: the issue with its transitions; Azure\nDevOps: the item and its type's states), after the write gate, which is unchanged:\nwrites on for the connection and `--allow-write`. `--transition` (Jira) and `--state`\n(Azure DevOps) still name the move exactly; give one or `--to`, not both.\n\n```bash\ntoil jira issue transition PAY-12 --to review --allow-write\ntoil ado work-item transition 42 --to done --allow-write\n```\n\n## Progress\n\nWhile a command runs, toil says what it's doing: each page a listing reads, and each\nrate-limited (429) request it waits to retry. On the command line these go to stderr,\none plain `[toil] \u2026` line each: a retry and how long toil waits always, piped or not,\nand pages only when stderr is a terminal. stdout still holds only the envelope. Over MCP they're progress notifications, sent when the\nclient's call asks for progress. A program using toil's API gets them, and every\nrequest too, through `onProgress` (**Using toil from a program**). They never change\nthe envelope.\n\n## Selecting fields\n\nTo get back only the fields you need, pass `--select <expression>` (`select` over\nMCP), a [JMESPath](https://jmespath.org/specification.html) expression applied to\n`data`, for example `--select \"issues[].{key: key, status: fields.status.name}\"`.\n`meta`, including `meta.page`, is left as it is. A bad expression is `INVALID_INPUT`\nbefore the command runs, with its position in `error.fix`; one that selects nothing\ngives `data: null` and a `SELECT_EMPTY` warning. An expression may build at most 16 MiB\nof JSON plus four times the size of the data, so one that multiplies the data (`[@,@]`\npiped into itself) is `INVALID_INPUT` too; select fewer fields or elements. The same\nholds for `toil wait --until`.\n\n## Big results\n\nA search or listing can return far more than you need to read. Two flags on every\ncommand (fields over MCP) keep it out of your context.\n\n**`--summary-file <file>`** (`summaryFile`) writes the whole of `data`, as JSON, to\nthat file in the workspace (it must not exist yet; toil never overwrites), and puts a\nsummary in `data` instead. Use it for any read that may return more than a page. Fixed\nrules pick the summary, the first that matches:\n\n| Result | `data` holds |\n|--------|--------------|\n| No list in it, 20 fields or fewer, and an estimated 1,500 tokens or fewer | The whole result |\n| 50 rows or fewer, and an estimated 1,500 tokens or fewer | The whole result |\n| No list, or rows that don't share 80% of their fields | `keys`, `lengths` (of each list, object and long text) and one `sample`, its long text cut short (a bare text keeps its first 2,000 characters) |\n| 500 rows or fewer | `fields` (what's beside the list), the first 20 `rows`, `stats` and `file` |\n| More than 500 rows | `fields`, the column `schema`, 10 `rows` spread from first to last, `stats` and `file`, with a `SUMMARY_LARGE` warning |\n\nThe rows are the result itself when it's a list, else the list in it with the most\ncells, its rows times their width (`issues` in `{ total, issues }`, `findings.results`\na level down, or `rows` beside a `db` query's `columns`). Size doesn't count, so one\nlong text can't make a one-row list the table, and a list of objects that names the\ncolumns of a sibling's list rows, or is exactly `{ name, type }` columns beside an\nempty list (a `db` query's `columns`), is never the table. Nested rows\nare compared by their dot paths (`fields.status.name`). `stats` has, for each column\n(the first 25), `nulls`, `distinct`, and `min` and `max` for numbers and dates (null\notherwise). Every summary is held to the 1,500-token budget: texts longer than 200\ncharacters are cut short (ending in `\u2026`), then rows are dropped from the end (a last\nrow still too wide has its texts cut to 40 characters, and goes only if that doesn't\nfit), fields\nbeside the rows are dropped from the end, and an outline's sample, lengths and keys\nare cut in that order. `meta.summary` says which rule applied (`rule`),\nhow many rows the full result has (`rows`), where they are (`table`), the `file`,\nthe token estimates (`tokens`, JSON characters / 3.5: an estimate, never a count),\nthe column count, and anything the budget trimmed. After a `SUMMARY_LARGE` warning,\nwork over the file rather than reading it in: a narrower query, `--select`, or a tool\nthat reads JSON. The file is written even when the whole result fits, so it's always\nthere; a read-only API call refuses `summaryFile`, since it writes a file.\n\n**`--output-format toon`** (`outputFormat: \"toon\"`) writes `data` as\n[TOON](https://github.com/toon-format/spec) text: a list of uniform rows becomes one\nheader (`rows[20]{key,status}:`) and one comma-separated line per row, so field names\nare paid for once rather than on every row. Only `data` changes: `ok`, `error` and\n`meta` stay JSON, and `meta.format` is `\"toon\"`. It pays off for tables; deeply\nnested data with few repeated rows can come out longer than JSON. `--output-format\njson` is the default, and output without either flag is exactly what it always was.\nBoth flags go together, the summary first:\n\n```bash\ntoil util deps scan --include-transitive --summary-file deps.json --output-format toon\n```\n\n## Waiting for something to finish\n\nTo wait for a build, a scan or a deployment to finish, don't call a read in a loop:\n`toil wait --until \"<expression>\" -- <read command>` runs it again every `--interval`\n(default 15s, at least 5s) until the JMESPath expression over its `data` is true (not\nnull, false or empty), for example\n`toil wait --until \"result != null\" -- jenkins run get my-job 42` or\n`toil wait --until \"projectStatus.status != 'NONE'\" --timeout 10m -- sonar quality-gate get --project my-app`.\nOver MCP it's the `wait` tool, with `tool` (the read's tool name), `input` (that tool's\ninput) and the same `until`, `interval` and `timeout`. It returns the read's last\nenvelope plus `meta.wait` (`until`, `attempts`, `elapsedMs`). `NETWORK` errors and\n`HTTP` 5xx or 429 answers are retried with backoff; any other error ends the wait with\nthat error. Past `--timeout` (at least 5s; default 30m, or `TOIL_TIMEOUT_MS`, cut to the maximum\nwith a `WAIT_TIMEOUT_CAPPED` warning when it is longer; at most the\n`\"wait\": { \"maxTimeout\" }` in config, default 1h) it's `TIMEOUT`, with the last `data`\nin `error.details.data`. Only reads can be waited on: a write is `INVALID_INPUT`.\n`--select` before `wait` applies to the final `data`; a `--select` after `--` belongs\nto the read, so `--until` sees what it selected. Other global flags go before `wait`,\n`--summary-file` and `--output-format` included, and shape the final `data`.\n\n## Writes\n\nReads are always allowed. A command that changes something, in a service, a database\nor a file on this machine outside toil's own config, needs both `writes: true` on the\nconnection it uses, set by a person in their config or with a\n`TOIL_CONN_<NAME>_WRITES` / `TOIL_<AREA>_WRITES` env var, and `--allow-write` on the\ncall (`allowWrite: true` over MCP). Without either it fails with `WRITE_DISABLED`,\nnaming what's missing. Over MCP a write tool isn't listed until writes are on, and\ndeletes are never tools. A command that is CLI only and has no connection yet\n(`toil skills marketplace add`) needs `--allow-write` alone.\n\n### Exceptions\n\nExactly four writes don't follow that rule. Each is the maintainer's choice, made\ndeliberately, and is listed here with how to avoid it.\n\n| Write | What it writes, and when | Why | To avoid it |\n|-------|--------------------------|-----|-------------|\n| **`toil skill install`** | With `--allow-write` alone (CLI only, no connection): the toil skill, into one agent's skills folder as `toil/`, recorded as `bundled`. | Its contents are fixed: the files embedded in toil, no third-party code. It replaces only a `toil/` folder it recorded as `bundled` and refuses any other. | Don't run it. |\n| **The toil skill keeping itself current** | With no `--allow-write`: a `toil/` skill folder recorded as `bundled`, and nothing else in a skills folder (never a marketplace or hand-made skill). Rewritten by any command that loads config, on the CLI or over MCP, when that command changed the config file (a connection added, changed or removed) or when the copy was written by another toil version. Said in `meta.warnings` as `SKILL_REWRITTEN`. | So an installed skill never describes connections you no longer have, or a toil you no longer run, with no update command to forget. The contents are fixed; the description holds only area and engine names checked against toil's own list, never a host or a credential; and a rewrite that fails is a `SKILL_REWRITE_FAILED` warning, never a failed command. | Don't install the skill with `toil skill install` (copy `skills/toil` yourself, or use the Claude Code plugin marketplace), or delete the installed `toil/` folder. A call with `--config <file>` never rewrites it. |\n| **`toil feedback`** | With no connection and no `--allow-write`: one bug report or feature request, sent to Imagile LLC, which files it as a public GitHub issue. Only with `--consent` on the call, or `yes` typed at a terminal after it shows the report. CLI only. | Feedback has no connection to hold a standing opt-in, so the approval of each report is the opt-in. It sends only what you typed, plus toil's version and commit, and is the one request toil makes to a host you didn't configure (**Feedback**, below). | Don't run it, or run it without `--consent`: it then sends nothing and shows what it would send. |\n| **The welcome menu's game save** | With no `--allow-write`: the game's progress, under the `\"game\"` key of `~/.toil/config.json`, every other key kept as it was. Only while you play Two Weeks' Notice in the menu bare `toil` opens. | It's a game a person plays at a terminal, and its save touches nothing but its own key. The save is sealed against tampering, not kept secret. | Don't play it. There is no setting to turn the save off. |\n\n## The raw API passthrough\n\nFor an endpoint no command covers, an HTTP area has `toil <area> api <METHOD> <path>`\n(`<area>_api` over MCP), which sends the connection's own credential to a path under\nits base URL. GET and HEAD are reads; other methods are writes, and `DELETE` is CLI\nonly. The area's reference describes it where the area has one (`jira.md`).\n\n## Files and the workspace\n\nFiles a command reads or writes (an `--input-file`, an upload, a download, a CSV\nreport) must be inside the workspace: `--workspace <dir>`, else `TOIL_WORKSPACE`,\nelse the working directory; under `toil mcp`, the client's root when it shares\nexactly one. Relative paths resolve against it, a path outside is refused with\n`INVALID_INPUT`, and nothing is ever overwritten. Under `toil mcp` with no single\nroot, a command that touches a file returns `NOT_CONFIGURED`: add `--workspace <dir>`\nto the server's args. A person can let commands reach any path with\n`\"bounds\": { \"files\": \"unbounded\" }` in their config, and every envelope then\ncarries a `BOUND_RELAXED` warning. A network path (`\\\\host\\share\\x`, `//host/share/x`)\nor a Windows device path (`\\\\?\\`, `\\\\.\\`) is refused with `INVALID_INPUT` before\nanything looks at it, relaxed or not, unless the workspace is itself a folder on that\nshare; copy the file into the workspace instead. Saved paths come back absolute, with forward\nslashes. Commands that run git need git on PATH and say\n`GIT_NOT_FOUND` without it; nothing else does.\n\n## Configuration\n\nConfiguration comes from environment variables, which always win, or from\n`~/.toil/config.json` (or the file passed with `--config`). A connection is one\ninstance of an area; `--connection <name>` picks one when there are several.\n`toil connections list` names them (never a secret), with `definedIn`: `file` for one\nin your config file, `env` for one made by env vars alone, which the connections\ncommands can't change. `toil connections test\n<name>` checks one with a single authenticated read, failing with the `AUTH`,\n`NETWORK` or config error a real command would. Setting up a connection, signing\nin, turning writes on and choosing a default are for a person: a bare `toil` in a\nterminal opens a menu for them.\n\n## Global flags\n\nGlobal flags go before or after the command: `--pretty`, `--verbose` (adds every\nrequest to `meta.requests`, credentials redacted), `--debug` (traces on stderr),\n`--config <file>`, `--output-file <file>` (the whole envelope to a file, CLI only),\n`--workspace <dir>`, `--select <expression>`, `--summary-file <file>` and\n`--output-format json|toon` (**Big results**). `--help` on any command lists its own\nflags.\n\n## Dossiers\n\n`dossiers.md` explains what a dossier is, with an example file field by field; this\nsection is the short form.\n\nA **dossier** holds what toil knows about one body of work: its repositories, and per\narea the keys a call needs (`project`, `owner`, a namespace per environment), which\nconnection to use (by name, or by `host`), and reference data such as board lists.\nIt holds no secret and can't add a host or turn on writes. toil reads dossiers on\nevery area command from `~/.toil/dossiers/`, the folders in `dossierPaths` (or\n`TOIL_DOSSIER_PATHS`), and `.toil/dossiers/` in the repository you're in, and uses\nthe one that applies: `--dossier <name|file>` (`dossier` over MCP, or\n`TOIL_DOSSIER`), else the one whose repo matches the folder by path or `origin`\nremote. `--cwd <dir>` (`cwd` over MCP) looks from another folder. A value you pass\nalways beats the dossier's, and `meta.context.dossier` says which dossier applied and\nwhy. When two different dossiers match, the call fails with `INVALID_INPUT` until you\npick one. A write on a connection a dossier chose is `WRITE_DISABLED` unless the\ndossier is in your own folder; pass `--connection` to choose it yourself. To see what\na call will use before making it: `toil dossiers context` (which dossier a folder\nresolves to and why), `toil dossiers show [name]` (per area: the connection and why,\nwhether writes are on, the environment and the inputs), `toil dossiers list`, and\n`toil dossiers check [name]`, which checks one locally and contacts no service.\n\nTo build one for a product: `toil repos scan` lists the git repositories under the\nworkspace. Then:\n- `toil dossiers init <name>` creates the dossier.\n- `toil dossiers add-repo <name> <folder|remote>` adds each repository.\n- `toil dossiers link <name> <area> --host <host> --set project=PAY [--for-repo <repo>]`\n says which connection an area uses and the keys it supplies.\n- `toil dossiers env <name> <env> <area> --set namespace=...` adds an environment.\n- `toil dossiers field <name> jira storyPoints customfield_10002` names a field, so\n `--field storyPoints=5` works.\n- `toil <area> check-dossier` checks a section against the service, for the call's\n environment (jira, jira-cloud, confluence, sonar, ado, bitbucket, github, openshift,\n dynatrace).\n- `toil dossiers export <name> --repo <root>` writes a shareable copy into a\n repository's `.toil/dossiers/`. It uses host selectors and no local paths, and toil\n never commits it.\n- `toil dossiers unlink <name> --area <area> [--env <env>]` removes a section (CLI only).\n- `toil dossiers import <file>` copies a teammate's into your own folder. A connection\n or host you lack is listed under `toSetUp`; toil never creates one.\n\nThese are local writes and need no `--allow-write`. Each refuses a value that's already\nset unless `--replace`. Over MCP they refuse to make a dossier select a connection\nwith writes on; the user does that on the command line, or under **Dossiers** in the\nmenu bare `toil` opens, which runs these same commands and asks them to type the\nconnection's name first.\n\n## The audit log\n\ntoil keeps a local audit log of every command it runs, through the CLI, MCP and the\nAPI: one JSON line per call in `~/.toil/audit/<yyyy-mm>.jsonl`, with the command, front\ndoor (`via`: `cli`, `mcp` or `api`, plus `caller` when a program named itself), connection, whether it wrote, the outcome, the redacted input and each request's\nmethod, URL and status. It never holds a secret, a header, a body or a row, and `db`\nSQL is kept only as a SHA-256 hash. `toil audit list` reads it back, newest first,\nwith `--since <date>`, `--command <name|area>`, `--connection <name>` and\n`--outcome <ok|failed|code>` and `--writes-only`; `toil audit path` says where it is and whether it's on. Six months are\nkept by default (`\"audit\": { \"keepMonths\": 12 }` changes that), and only a person can\nturn it off, with `\"audit\": { \"enabled\": false }` in `~/.toil/config.json`. A call\nwhose line couldn't be written still succeeds, with an `AUDIT_WRITE_FAILED` warning.\n\n`toil audit stats` summarizes the same log, and reads nothing else. Over a window\n(`--since`, `--until`; by default from midnight UTC 30 days ago to now) it returns\n`totals` and one entry in `groups` per value of `--by command|area|connection|caller|via|outcome|day`\n(repeat `--by` for a cross-tab; the default is `command`; `day` is the UTC date):\n`calls`, `ok`, `failed`, the top three `errors` with each code's general `fix` (the log\nkeeps the code, never the call's own message), the nearest-rank `durationMs.median` and\n`p95`, `writes` and `writeShare`, and `firstSeen` / `lastSeen`. Groups come most calls\nfirst, or in date order when `day` comes first. `--area`, `--command`, `--caller` and\n`--outcome` filter it, and `--unused` adds `unused`: every registered command, within\nthe area and command filters, with no matching call in the window, and whether MCP\nserves it. It never groups by an input's value, so a hashed statement stays a hash.\n\n```bash\ntoil audit stats --by command --unused --area jira\ntoil audit stats --by day --by via --since 2026-10-01 --until 2026-10-18\ntoil audit list --command \"jira issue get\" --outcome failed --limit 20\n```\n\n## Using toil from a program\n\nA Node program can call toil in-process instead of running `toil` and parsing stdout.\n`@imagile-dev/toil/api` is a supported entry point of the same package, with its own\ntypes, and it adds no dependency: it is the same bundle as the CLI. Loading it runs nothing, even\nwhen your own build bundles it in: only toil's bin starts the CLI.\n\n```js\nimport { contractVersion, execute, registry, version } from '@imagile-dev/toil/api';\n\nif (contractVersion !== 1) throw new Error(`Needs toil's contract 1; toil ${version} has ${contractVersion}.`);\nconst envelope = await execute('jira issue search', { jql: 'project = PAY', limit: 50 }, {\n readOnly: true,\n caller: 'nightly-sync',\n onProgress: (event) => console.error(event.message),\n});\n```\n\n- **`execute(command, input, options)`** runs one command and returns its envelope,\n exactly as the CLI prints it. `command` is the name `meta.command` reports\n (`jira issue search`); `input` is the command's MCP fields, checked strictly. It never\n throws: an unknown command or a bad option is an `INVALID_INPUT` envelope.\n Connections, env vars, the credential store, dossiers, the workspace (the program's\n working directory, else `workspace`), the write gate and the audit log all apply as\n they do on the CLI. It serves what MCP serves: commands that prompt or change\n connections, and deletes, stay on the CLI, except as `person` below allows.\n- **`options`**: `readOnly` refuses, with `WRITE_DISABLED` and before anything is sent,\n any call that would change anything, whatever the config says: a write to a service,\n and a local one too (toil's config or dossiers, a download, a file named with\n `out`). A read-only call writes nothing but its audit line. `caller` names the program in the audit log (lowercase letters, digits,\n `.`, `_` and `-`, up to 64), and `actor`, in the same characters, who it called\n for (Toil UI names an agent assignment, `assignment-<id>`). `signal` cancels the call (`CANCELLED`). `onProgress`\n hears every request (redacted URL, status, time), page and retry. `config`,\n `workspace` and `verbose` match `--config`, `--workspace` and `--verbose`.\n- **`person`** is for a program with its own interface for a person, such as Toil\n UI's settings pages. It is `{ ask(question) }`, and with it `execute()` also runs\n the connections commands a person runs on a terminal: `connections add`, `login`,\n `remove`, `writes` and `default`, and `feedback` (`registry.personCommands`). Each\n question arrives as `{ id, text, secret, fallback }`, and `ask` returns what the\n person typed. The `id` is one of `area`, `setting:<key>`, `secret:<key>`, `confirm`\n (`y` saves what they reviewed), `confirm-name` (the connection's name, typed to\n turn writes on) or `consent` (`yes` sends the feedback report and disclaimer the\n question shows, **Feedback**, above). With `readOnly`, nothing is asked: `feedback`\n only previews. Return `undefined` for a question they weren't asked, and the\n command saves or sends nothing (`CANCELLED`). A secret goes from the answer to the OS\n credential store: it is never in the input, the envelope or the audit log. The\n program must ask a person and pass on their answers. Nothing about this lets an\n agent run these commands.\n- **`registry`** lists every command `execute()` serves: its name, MCP tool name,\n whether it writes to a service (`writes`) or on this machine (`writesLocal`), and\n its input's JSON Schema. It also lists the areas, each with `connection`: the\n fields `connections add` asks for, in order, each with `secret`, `password`,\n `default` and `required`.\n- **`version`** and **`contractVersion`** are what `toil version` reports. Check\n `contractVersion` before relying on anything else. `toil version` also reports\n `commit`, the 40-character hash of the commit the build came from (`null` when the\n build didn't record one), which is what a bug report from a terminal names.\n- **`mapOwi(input, options)`** maps envelopes you already hold (one, an array, or\n JSON Lines text) to Open Work Items and pull requests to changes, the way `toil\n util owi map` does (`util.md`), synchronously and without the schema check:\n `{ items, changes, histories, skipped, warnings }`. `options.fields` is a dossier\n section's `fields` object (`{ estimate: 'customfield_10234', estimateUnit: 'points' }`),\n `command` names the command for bare `data`, `key` the item a keyless history\n belongs to, `keyPatterns` where work item keys in a pull request point\n (`['PAY-{n}=corp-jira']`), and `authorKinds` the author kinds set by hand\n (`{ 'release-bot': 'BOT' }`). A refused input throws, with a fix. **`owiVersion`** is the OWI version items carry,\n and **`owiSchema`** their JSON Schema; `execute('util owi map', { text })` maps\n and validates in one call.\n- **`findSimilar(records, request, options)`** finds likely duplicates among OWI\n records you already hold (mapOwi's `items`, or the text `util owi map` printed),\n scored the way `toil util owi similar` scores them (`util.md`), in-process:\n `{ query }` ranks them against some text, `{ item }` against one of them by OWI\n id, and `{ pairs: true }` lists likely duplicate pairs. `options` takes\n `fields`, `limit` and `threshold`. It returns `{ mode, method, count, matches,\n pairs, search }`, each match and pair with its `score` and `why`, the same for\n the same records every time. For a very large set, use\n `execute('util owi similar', \u2026)`, which runs in a worker with a deadline.\n\nWhat `@imagile-dev/toil/api` exports, and the types it names, follow the command\ncontract: they change only additively unless `contractVersion` goes up. Anything else\nin the package is internal.\n\n## Feedback\n\n`toil feedback bug|feature` sends a bug report or a feature request to Imagile LLC,\nwhere it becomes a public GitHub issue in `imagile-dev/toil`, and the reporter is\nemailed when it's filed and when it closes. It is CLI only, never an MCP tool, and the\none request toil makes to a host you didn't configure. Every report carries this\ndisclaimer, version 1, and nothing is sent until the person sending it agrees to it:\n\n> Your report is sent to Imagile LLC to improve toil, and it becomes a public GitHub\n> issue in imagile-dev/toil. Your email address stays private: it is used only to tell\n> you about your issue. Before you send, remove company data: internal URLs and\n> hostnames, ticket keys, repository and project names, people's names, other\n> identifiers and credentials. You are responsible for what you send.\n\n```bash\ntoil feedback bug --title \"jira issue search ignores --limit\" --body \"toil jira issue search --limit 5 returns 50 issues.\" --email you@example.com\n```\n\n| Flag | Meaning |\n|------|---------|\n| `--title <text>` | One line, up to 120 characters |\n| `--body <text>` | The details, up to 4000 characters |\n| `--email <address>` | The reporter's own address, kept private |\n| `--input-file <file>` | JSON with any of `kind`, `title`, `body` and `email`, for long text; a flag beats the file, and `-` reads stdin |\n| `--consent` | Send it. Without it nothing is sent |\n\nWithout `--consent`, the command sends nothing. On a terminal it shows the report and\nthe disclaimer and asks; anywhere else it returns `sent: false`, the exact `report`\nit would send, the `disclaimer`, `consentVersion` and how to approve, with a\n`FEEDBACK_NOT_SENT` warning. With `--consent` it sends that same report and returns\n`sent: true` and the endpoint's message. The report is the kind, title, body and email\ngiven, plus `version`, `commit` and `consent` (the disclaimer's version). toil never\nadds config, connection names, hosts or tokens. A build that doesn't know its commit\npreviews but can't send (`UNSUPPORTED`); the form at\nhttps://imagile-dev.github.io/toil/feedback/ works from any browser.\n\n**An agent sending feedback for a user follows every step, in order, every time:**\n\n1. **Only when the user asks.** Never offer to send a report on your own initiative,\n and never send one because a command failed.\n2. **Scrub it.** Replace company data with neutral placeholders before the user sees\n the draft: internal URLs and hostnames (`jira.imagile.dev`), ticket keys\n (`PROJ-123`), repository, project and team names (`my-repo`), people's names\n (`a colleague`), email addresses other than the reporter's own, IDs, tokens,\n passwords and anything else credential-shaped. Keep toil's own command names,\n flags and error codes; they're what makes a report useful.\n3. **Show it.** Run the command without `--consent` and show the user the full\n `data.report` it returned, and the `data.disclaimer`, word for word.\n4. **Ask.** Get the user's explicit yes in chat to sending that exact report. A yes to\n an earlier draft, or to feedback in general, isn't one.\n5. **Send it.** Only then run the same command again with `--consent`, unchanged. If\n the user asks for any change, make it, and go back to step 3.\n\nThrough `@imagile-dev/toil/api`, `feedback` runs only for a `person` (below), whose\n`yes` to the `consent` question sends it; the `consent` field is refused there, and a\n`readOnly` call only previews. `TOIL_FEEDBACK_URL` points the command at a local copy\nof the feedback function for testing, and takes only a loopback address\n(`http://127.0.0.1:7071`).\n\n## Certificates and proxies\n\ntoil trusts the OS certificate store and Node's bundled CAs, and uses `HTTPS_PROXY` /\n`HTTP_PROXY` / `NO_PROXY` when they're set. A `NETWORK` error about an untrusted\ncertificate means the CA is in neither; `NODE_EXTRA_CA_CERTS` adds it.\n",
140430
+ "core.md": "---\ndescription: What every toil command shares, in detail - the envelope and errors, the contract version, --select, big results (--summary-file and --output-format toon), toil wait, paging and progress, writes and their exceptions, global flags, files and the workspace, configuration, the raw API passthrough, dossiers, the audit log, using toil from a program (@imagile-dev/toil/api), sending feedback, certificates and proxies\n---\n\n# Using toil\n\n`SKILL.md` has the rules every call needs. This page has the detail behind them, for\nwhen a call needs more than a command's own flags.\n\nThe jira, jira-cloud, ado and ado-cloud commands are `toil <area> <resource> <action>\n[ids...]`: ids are positional, everything else is a flag, and `toil <area> <resource>\n--help` lists what a resource can do (`toil jira issue --help`).\n\n## The envelope and errors\n\nEvery command prints one JSON envelope on stdout: `{ ok, data, error, meta }`.\nCheck `ok`; on failure, `error.code` says what kind of failure it was and `error.fix`\nsays what to do about it. New codes may appear in any release, so treat a code you\ndon't know as a generic failure. `meta.warnings` lists anything worth knowing that\nisn't a failure, such as a truncated result. `meta.context` says which connection a\ncall used and how it was chosen, and where any project, repo or environment it\nresolved came from. `meta.lint`, on the `db` commands that run SQL you wrote, names\nthe engine whose dialect toil checked it against and the rules that ran (`db.md`,\n**Pre-flight lint**). `--pretty` formats the output for people.\n\n`meta.contractVersion` (also in `toil version`) is the version of toil's command\ncontract: its commands, flags, `data` fields, envelope and error codes. It goes up only\nwith a breaking change, so a script or program built against one version works with\nevery toil that reports it.\n\n## Paging\n\nPaged results put the next page's cursor in `meta.page.nextCursor` (null on the last\npage) and the page size in `meta.page.limit`. Pass the cursor back with the\ncommand's own paging flag, which its reference names.\n\n## Moving work items by intent\n\n`jira issue transition`, `jira-cloud issue transition`, `ado work-item transition` and\n`ado-cloud work-item transition` take `--to <intent>` (`to` over MCP): `start`,\n`review`, `done`, `reopen`, or a status name. toil resolves it against the moves that\none item offers right now, by its own workflow, because a workflow belongs to the issue\nor work item type: a Story may go through In Review while a Task goes straight to Done.\nIn order, the first that gives exactly one move wins:\n\n1. **The dossier's pin** for the item's type: `\"transitions\": { \"Story\": { \"review\":\n \"Peer Review\" } }` in the area's section (**Dossiers**, below).\n2. **An exact name**: a transition or status called what you passed, ignoring case.\n3. **The intent's status category**: Jira's To Do, In Progress and Done categories\n serve `reopen`, `start` and `done`, and Jira files review under In Progress, so a\n status there whose name says review (In Review, Code Review) serves `review`; Azure DevOps'\n Proposed, InProgress, Resolved and Completed serve `reopen`, `start`, `review` and\n `done`. When several moves share the category, a name that starts a word with the\n intent (`Submit for Review`) picks one.\n4. **A name that says it**: the one move whose name or target status starts a word with\n the intent.\n\nIt never guesses. No match, more than one, or an item already where the intent leads is\n`INVALID_INPUT`, and the fix lists every move the item offers, by name, target status,\ncategory and id. On success `meta.transition` says what was resolved: `{ intent,\ntransition, toStatus, resolvedBy }`, `resolvedBy` being `dossier`, `status`,\n`category` or `name`. Resolving only reads (Jira: the issue with its transitions; Azure\nDevOps: the item and its type's states), after the write gate, which is unchanged:\nwrites on for the connection and `--allow-write`. `--transition` (Jira) and `--state`\n(Azure DevOps) still name the move exactly; give one or `--to`, not both.\n\n```bash\ntoil jira issue transition PAY-12 --to review --allow-write\ntoil ado work-item transition 42 --to done --allow-write\n```\n\n## Ticket the work\n\nBefore you start work that no ticket covers (a prompt or a branch that names no\nissue key), find the open ticket it belongs to and ask the person what to do with\nit. Never decide on your own, and never start the work untracked without asking.\n\n1. **List the person's open items** in the dossier's trackers (`toil dossiers show`\n names them): theirs and not done, through each tracker's own search, mapped\n with `toil util owi map`. Each tracker's page gives its search under **Ticket the\n work**.\n2. **Rank them against the work**, by the prompt or the branch name:\n `toil util owi similar --query \"<text>\"`. Each match has a `score` and a `why`,\n the shared words that drove it.\n3. **Ask the person**, showing the top matches (up to three) with their `why`,\n which of three to do:\n - **Attach** the work to a match. Nothing is written: use its key in the branch\n name and in every commit message.\n - **Create a sub-task** under it.\n - **Create a new ticket**, letting the dossier and the connection fill the\n project and the issue type.\n\n With no match (an `OWI_SIMILAR_NO_MATCH` warning), say there is no likely\n ticket and suggest creating one. Don't lower `--threshold` to find something.\n4. **A sub-task or a new ticket is a write.** Show the exact command first, and run\n it only on the person's yes to that one item, with writes on for the connection\n and `--allow-write` (**Writes**, below).\n\n```bash\ntoil jira issue search --jql \"assignee = currentUser() AND statusCategory != Done\" --fields summary,description,status,issuetype,labels,parent | toil util owi map | toil util owi similar --query \"Card payments time out at checkout\"\n```\n\nOver MCP, pass the `util_owi_map` envelope to `util_owi_similar` as `text`, with\n`query`.\n\n## Progress\n\nWhile a command runs, toil says what it's doing: each page a listing reads, and each\nrate-limited (429) request it waits to retry. On the command line these go to stderr,\none plain `[toil] \u2026` line each: a retry and how long toil waits always, piped or not,\nand pages only when stderr is a terminal. stdout still holds only the envelope. Over MCP they're progress notifications, sent when the\nclient's call asks for progress. A program using toil's API gets them, and every\nrequest too, through `onProgress` (**Using toil from a program**). They never change\nthe envelope.\n\n## Selecting fields\n\nTo get back only the fields you need, pass `--select <expression>` (`select` over\nMCP), a [JMESPath](https://jmespath.org/specification.html) expression applied to\n`data`, for example `--select \"issues[].{key: key, status: fields.status.name}\"`.\n`meta`, including `meta.page`, is left as it is. A bad expression is `INVALID_INPUT`\nbefore the command runs, with its position in `error.fix`; one that selects nothing\ngives `data: null` and a `SELECT_EMPTY` warning. An expression may build at most 16 MiB\nof JSON plus four times the size of the data, so one that multiplies the data (`[@,@]`\npiped into itself) is `INVALID_INPUT` too; select fewer fields or elements. The same\nholds for `toil wait --until`.\n\n## Big results\n\nA search or listing can return far more than you need to read. Two flags on every\ncommand (fields over MCP) keep it out of your context.\n\n**`--summary-file <file>`** (`summaryFile`) writes the whole of `data`, as JSON, to\nthat file in the workspace (it must not exist yet; toil never overwrites), and puts a\nsummary in `data` instead. Use it for any read that may return more than a page. Fixed\nrules pick the summary, the first that matches:\n\n| Result | `data` holds |\n|--------|--------------|\n| No list in it, 20 fields or fewer, and an estimated 1,500 tokens or fewer | The whole result |\n| 50 rows or fewer, and an estimated 1,500 tokens or fewer | The whole result |\n| No list, or rows that don't share 80% of their fields | `keys`, `lengths` (of each list, object and long text) and one `sample`, its long text cut short (a bare text keeps its first 2,000 characters) |\n| 500 rows or fewer | `fields` (what's beside the list), the first 20 `rows`, `stats` and `file` |\n| More than 500 rows | `fields`, the column `schema`, 10 `rows` spread from first to last, `stats` and `file`, with a `SUMMARY_LARGE` warning |\n\nThe rows are the result itself when it's a list, else the list in it with the most\ncells, its rows times their width (`issues` in `{ total, issues }`, `findings.results`\na level down, or `rows` beside a `db` query's `columns`). Size doesn't count, so one\nlong text can't make a one-row list the table, and a list of objects that names the\ncolumns of a sibling's list rows, or is exactly `{ name, type }` columns beside an\nempty list (a `db` query's `columns`), is never the table. Nested rows\nare compared by their dot paths (`fields.status.name`). `stats` has, for each column\n(the first 25), `nulls`, `distinct`, and `min` and `max` for numbers and dates (null\notherwise). Every summary is held to the 1,500-token budget: texts longer than 200\ncharacters are cut short (ending in `\u2026`), then rows are dropped from the end (a last\nrow still too wide has its texts cut to 40 characters, and goes only if that doesn't\nfit), fields\nbeside the rows are dropped from the end, and an outline's sample, lengths and keys\nare cut in that order. `meta.summary` says which rule applied (`rule`),\nhow many rows the full result has (`rows`), where they are (`table`), the `file`,\nthe token estimates (`tokens`, JSON characters / 3.5: an estimate, never a count),\nthe column count, and anything the budget trimmed. After a `SUMMARY_LARGE` warning,\nwork over the file rather than reading it in: a narrower query, `--select`, or a tool\nthat reads JSON. The file is written even when the whole result fits, so it's always\nthere; a read-only API call refuses `summaryFile`, since it writes a file.\n\n**`--output-format toon`** (`outputFormat: \"toon\"`) writes `data` as\n[TOON](https://github.com/toon-format/spec) text: a list of uniform rows becomes one\nheader (`rows[20]{key,status}:`) and one comma-separated line per row, so field names\nare paid for once rather than on every row. Only `data` changes: `ok`, `error` and\n`meta` stay JSON, and `meta.format` is `\"toon\"`. It pays off for tables; deeply\nnested data with few repeated rows can come out longer than JSON. `--output-format\njson` is the default, and output without either flag is exactly what it always was.\nBoth flags go together, the summary first:\n\n```bash\ntoil util deps scan --include-transitive --summary-file deps.json --output-format toon\n```\n\n## Waiting for something to finish\n\nTo wait for a build, a scan or a deployment to finish, don't call a read in a loop:\n`toil wait --until \"<expression>\" -- <read command>` runs it again every `--interval`\n(default 15s, at least 5s) until the JMESPath expression over its `data` is true (not\nnull, false or empty), for example\n`toil wait --until \"result != null\" -- jenkins run get my-job 42` or\n`toil wait --until \"projectStatus.status != 'NONE'\" --timeout 10m -- sonar quality-gate get --project my-app`.\nOver MCP it's the `wait` tool, with `tool` (the read's tool name), `input` (that tool's\ninput) and the same `until`, `interval` and `timeout`. It returns the read's last\nenvelope plus `meta.wait` (`until`, `attempts`, `elapsedMs`). `NETWORK` errors and\n`HTTP` 5xx or 429 answers are retried with backoff; any other error ends the wait with\nthat error. Past `--timeout` (at least 5s; default 30m, or `TOIL_TIMEOUT_MS`, cut to the maximum\nwith a `WAIT_TIMEOUT_CAPPED` warning when it is longer; at most the\n`\"wait\": { \"maxTimeout\" }` in config, default 1h) it's `TIMEOUT`, with the last `data`\nin `error.details.data`. Only reads can be waited on: a write is `INVALID_INPUT`.\n`--select` before `wait` applies to the final `data`; a `--select` after `--` belongs\nto the read, so `--until` sees what it selected. Other global flags go before `wait`,\n`--summary-file` and `--output-format` included, and shape the final `data`.\n\n## Writes\n\nReads are always allowed. A command that changes something, in a service, a database\nor a file on this machine outside toil's own config, needs both `writes: true` on the\nconnection it uses, set by a person in their config or with a\n`TOIL_CONN_<NAME>_WRITES` / `TOIL_<AREA>_WRITES` env var, and `--allow-write` on the\ncall (`allowWrite: true` over MCP). Without either it fails with `WRITE_DISABLED`,\nnaming what's missing. Over MCP a write tool isn't listed until writes are on, and\ndeletes are never tools. A command that is CLI only and has no connection yet\n(`toil skills marketplace add`) needs `--allow-write` alone.\n\n### Exceptions\n\nExactly four writes don't follow that rule. Each is the maintainer's choice, made\ndeliberately, and is listed here with how to avoid it.\n\n| Write | What it writes, and when | Why | To avoid it |\n|-------|--------------------------|-----|-------------|\n| **`toil skill install`** | With `--allow-write` alone (CLI only, no connection): the toil skill, into one agent's skills folder as `toil/`, recorded as `bundled`. | Its contents are fixed: the files embedded in toil, no third-party code. It replaces only a `toil/` folder it recorded as `bundled` and refuses any other. | Don't run it. |\n| **The toil skill keeping itself current** | With no `--allow-write`: a `toil/` skill folder recorded as `bundled`, and nothing else in a skills folder (never a marketplace or hand-made skill). Rewritten by any command that loads config, on the CLI or over MCP, when that command changed the config file (a connection added, changed or removed) or when the copy was written by another toil version. Said in `meta.warnings` as `SKILL_REWRITTEN`. | So an installed skill never describes connections you no longer have, or a toil you no longer run, with no update command to forget. The contents are fixed; the description holds only area and engine names checked against toil's own list, never a host or a credential; and a rewrite that fails is a `SKILL_REWRITE_FAILED` warning, never a failed command. | Don't install the skill with `toil skill install` (copy `skills/toil` yourself, or use the Claude Code plugin marketplace), or delete the installed `toil/` folder. A call with `--config <file>` never rewrites it. |\n| **`toil feedback`** | With no connection and no `--allow-write`: one bug report or feature request, sent to Imagile LLC, which files it as a public GitHub issue. Only with `--consent` on the call, or `yes` typed at a terminal after it shows the report. CLI only. | Feedback has no connection to hold a standing opt-in, so the approval of each report is the opt-in. It sends only what you typed, plus toil's version and commit, and is the one request toil makes to a host you didn't configure (**Feedback**, below). | Don't run it, or run it without `--consent`: it then sends nothing and shows what it would send. |\n| **The welcome menu's game save** | With no `--allow-write`: the game's progress, under the `\"game\"` key of `~/.toil/config.json`, every other key kept as it was. Only while you play Two Weeks' Notice in the menu bare `toil` opens. | It's a game a person plays at a terminal, and its save touches nothing but its own key. The save is sealed against tampering, not kept secret. | Don't play it. There is no setting to turn the save off. |\n\n## The raw API passthrough\n\nFor an endpoint no command covers, an HTTP area has `toil <area> api <METHOD> <path>`\n(`<area>_api` over MCP), which sends the connection's own credential to a path under\nits base URL. GET and HEAD are reads; other methods are writes, and `DELETE` is CLI\nonly. The area's reference describes it where the area has one (`jira.md`).\n\n## Files and the workspace\n\nFiles a command reads or writes (an `--input-file`, an upload, a download, a CSV\nreport) must be inside the workspace: `--workspace <dir>`, else `TOIL_WORKSPACE`,\nelse the working directory; under `toil mcp`, the client's root when it shares\nexactly one. Relative paths resolve against it, a path outside is refused with\n`INVALID_INPUT`, and nothing is ever overwritten. Under `toil mcp` with no single\nroot, a command that touches a file returns `NOT_CONFIGURED`: add `--workspace <dir>`\nto the server's args. A person can let commands reach any path with\n`\"bounds\": { \"files\": \"unbounded\" }` in their config, and every envelope then\ncarries a `BOUND_RELAXED` warning. A network path (`\\\\host\\share\\x`, `//host/share/x`)\nor a Windows device path (`\\\\?\\`, `\\\\.\\`) is refused with `INVALID_INPUT` before\nanything looks at it, relaxed or not, unless the workspace is itself a folder on that\nshare; copy the file into the workspace instead. Saved paths come back absolute, with forward\nslashes. Commands that run git need git on PATH and say\n`GIT_NOT_FOUND` without it; nothing else does.\n\n## Configuration\n\nConfiguration comes from environment variables, which always win, or from\n`~/.toil/config.json` (or the file passed with `--config`). A connection is one\ninstance of an area; `--connection <name>` picks one when there are several.\n`toil connections list` names them (never a secret), with `definedIn`: `file` for one\nin your config file, `env` for one made by env vars alone, which the connections\ncommands can't change. `toil connections test\n<name>` checks one with a single authenticated read, failing with the `AUTH`,\n`NETWORK` or config error a real command would. Setting up a connection, signing\nin, turning writes on and choosing a default are for a person: a bare `toil` in a\nterminal opens a menu for them.\n\nWhen `toil connections add` or `login` asks for a secret, the terminal shows one `\u2022`\nper character typed or pasted (Backspace removes one, Ctrl+U clears them), never the\ncharacters, and after Enter says how many arrived: `Received 40 characters.` Before\nanything is stored, the paste is checked. Spaces, tabs or newlines around it are\ntrimmed and the line says so (`Received 40 characters (removed a trailing\nnewline).`); a value in quotes, or starting with `Bearer ` or `token `, is asked\nabout (`This starts with \"Bearer \". Store it without that? [Y/n]`), never changed\nsilently; a line break in the middle (or, for a token, a space) is refused, since\nthe paste most likely took two lines, and asked for again; and an empty answer\nasks again where the secret is required, or says `Kept the existing secret.` where\n`login` keeps the one stored. Toil UI's password fields run the same checks, in the\nsame words.\n\n## Global flags\n\nGlobal flags go before or after the command: `--pretty`, `--verbose` (adds every\nrequest to `meta.requests`, credentials redacted), `--debug` (traces on stderr),\n`--config <file>`, `--output-file <file>` (the whole envelope to a file, CLI only),\n`--workspace <dir>`, `--select <expression>`, `--summary-file <file>` and\n`--output-format json|toon` (**Big results**). `--help` on any command lists its own\nflags.\n\n## Dossiers\n\n`dossiers.md` explains what a dossier is, with an example file field by field; this\nsection is the short form.\n\nA **dossier** holds what toil knows about one body of work: its repositories, and per\narea the keys a call needs (`project`, `owner`, a namespace per environment), which\nconnection to use (by name, or by `host`), and reference data such as board lists.\nIt holds no secret and can't add a host or turn on writes. toil reads dossiers on\nevery area command from `~/.toil/dossiers/`, the folders in `dossierPaths` (or\n`TOIL_DOSSIER_PATHS`), and `.toil/dossiers/` in the repository you're in, and uses\nthe one that applies: `--dossier <name|file>` (`dossier` over MCP, or\n`TOIL_DOSSIER`), else the one whose repo matches the folder by path or `origin`\nremote. `--cwd <dir>` (`cwd` over MCP) looks from another folder. A value you pass\nalways beats the dossier's, and `meta.context.dossier` says which dossier applied and\nwhy. When two different dossiers match, the call fails with `INVALID_INPUT` until you\npick one. A write on a connection a dossier chose is `WRITE_DISABLED` unless the\ndossier is in your own folder; pass `--connection` to choose it yourself. To see what\na call will use before making it: `toil dossiers context` (which dossier a folder\nresolves to and why), `toil dossiers show [name]` (per area: the connection and why,\nwhether writes are on, the environment and the inputs), `toil dossiers list`, and\n`toil dossiers check [name]`, which checks one locally and contacts no service.\n\nIn a repository that already has one checked in, `toil dossiers onboard` sets you\nup: for each area it finds your connection on the dossier's host, offers to add one\nyou lack (asking for the token on the terminal), asks which to pin in your own copy\nwhen several match, then runs `dossiers check` and one test read per connection. It\nis CLI only; with no terminal, or `--plan`, it adds no connection and says what each\narea needs.\n\nTo build one for a product: `toil repos scan` lists the git repositories under the\nworkspace. Then:\n- `toil dossiers init <name>` creates the dossier; `--shared` creates it in the\n repository's `.toil/dossiers/` for the team, and a `--connection` linked into a\n shared dossier is recorded as that connection's `host`.\n- `toil dossiers add-repo <name> <folder|remote>` adds each repository.\n- `toil dossiers link <name> <area> --host <host> --set project=PAY [--for-repo <repo>]`\n says which connection an area uses and the keys it supplies.\n- `toil dossiers env <name> <env> <area> --set namespace=...` adds an environment.\n- `toil dossiers field <name> jira storyPoints customfield_10002` names a field, so\n `--field storyPoints=5` works.\n- `toil <area> check-dossier` checks a section against the service, for the call's\n environment (jira, jira-cloud, confluence, sonar, ado, bitbucket, github, openshift,\n dynatrace).\n- `toil dossiers export <name> --repo <root>` writes a shareable copy into a\n repository's `.toil/dossiers/`. It uses host selectors and no local paths, and toil\n never commits it.\n- `toil dossiers unlink <name> --area <area> [--env <env>]` removes a section (CLI only).\n- `toil dossiers import <file>` copies a teammate's into your own folder. A connection\n or host you lack is listed under `toSetUp`; toil never creates one.\n\nThese are local writes and need no `--allow-write`. Each refuses a value that's already\nset unless `--replace`. Over MCP they refuse to make a dossier select a connection\nwith writes on; the user does that on the command line, or under **Dossiers** in the\nmenu bare `toil` opens, which runs these same commands and asks them to type the\nconnection's name first.\n\n## The audit log\n\ntoil keeps a local audit log of every command it runs, through the CLI, MCP and the\nAPI: one JSON line per call in `~/.toil/audit/<yyyy-mm>.jsonl`, with the command, front\ndoor (`via`: `cli`, `mcp` or `api`, plus `caller` when a program named itself), connection, whether it wrote, the outcome, the redacted input and each request's\nmethod, URL and status. It never holds a secret, a header, a body or a row, and `db`\nSQL is kept only as a SHA-256 hash. `toil audit list` reads it back, newest first,\nwith `--since <date>`, `--command <name|area>`, `--connection <name>` and\n`--outcome <ok|failed|code>` and `--writes-only`; `toil audit path` says where it is and whether it's on. Six months are\nkept by default (`\"audit\": { \"keepMonths\": 12 }` changes that), and only a person can\nturn it off, with `\"audit\": { \"enabled\": false }` in `~/.toil/config.json`. A call\nwhose line couldn't be written still succeeds, with an `AUDIT_WRITE_FAILED` warning.\n\n`toil audit stats` summarizes the same log, and reads nothing else. Over a window\n(`--since`, `--until`; by default from midnight UTC 30 days ago to now) it returns\n`totals` and one entry in `groups` per value of `--by command|area|connection|caller|via|outcome|day`\n(repeat `--by` for a cross-tab; the default is `command`; `day` is the UTC date):\n`calls`, `ok`, `failed`, the top three `errors` with each code's general `fix` (the log\nkeeps the code, never the call's own message), the nearest-rank `durationMs.median` and\n`p95`, `writes` and `writeShare`, and `firstSeen` / `lastSeen`. Groups come most calls\nfirst, or in date order when `day` comes first. `--area`, `--command`, `--caller` and\n`--outcome` filter it, and `--unused` adds `unused`: every registered command, within\nthe area and command filters, with no matching call in the window, and whether MCP\nserves it. It never groups by an input's value, so a hashed statement stays a hash.\n\n```bash\ntoil audit stats --by command --unused --area jira\ntoil audit stats --by day --by via --since 2026-10-01 --until 2026-10-18\ntoil audit list --command \"jira issue get\" --outcome failed --limit 20\n```\n\n## Using toil from a program\n\nA Node program can call toil in-process instead of running `toil` and parsing stdout.\n`@imagile-dev/toil/api` is a supported entry point of the same package, with its own\ntypes, and it adds no dependency: it is the same bundle as the CLI. Loading it runs nothing, even\nwhen your own build bundles it in: only toil's bin starts the CLI.\n\n```js\nimport { contractVersion, execute, registry, version } from '@imagile-dev/toil/api';\n\nif (contractVersion !== 1) throw new Error(`Needs toil's contract 1; toil ${version} has ${contractVersion}.`);\nconst envelope = await execute('jira issue search', { jql: 'project = PAY', limit: 50 }, {\n readOnly: true,\n caller: 'nightly-sync',\n onProgress: (event) => console.error(event.message),\n});\n```\n\n- **`execute(command, input, options)`** runs one command and returns its envelope,\n exactly as the CLI prints it. `command` is the name `meta.command` reports\n (`jira issue search`); `input` is the command's MCP fields, checked strictly. It never\n throws: an unknown command or a bad option is an `INVALID_INPUT` envelope.\n Connections, env vars, the credential store, dossiers, the workspace (the program's\n working directory, else `workspace`), the write gate and the audit log all apply as\n they do on the CLI. It serves what MCP serves: commands that prompt or change\n connections, and deletes, stay on the CLI, except as `person` below allows.\n- **`options`**: `readOnly` refuses, with `WRITE_DISABLED` and before anything is sent,\n any call that would change anything, whatever the config says: a write to a service,\n and a local one too (toil's config or dossiers, a download, a file named with\n `out`). A read-only call writes nothing but its audit line. `caller` names the program in the audit log (lowercase letters, digits,\n `.`, `_` and `-`, up to 64), and `actor`, in the same characters, who it called\n for (Toil UI names an agent assignment, `assignment-<id>`). `signal` cancels the call (`CANCELLED`). `onProgress`\n hears every request (redacted URL, status, time), page and retry. `config`,\n `workspace` and `verbose` match `--config`, `--workspace` and `--verbose`.\n- **`person`** is for a program with its own interface for a person, such as Toil\n UI's settings pages. It is `{ ask(question) }`, and with it `execute()` also runs\n the connections commands a person runs on a terminal: `connections add`, `login`,\n `remove`, `writes` and `default`, `dossiers onboard`, and `feedback`\n (`registry.personCommands`). Each question arrives as `{ id, text, secret,\n fallback }`, and `ask` returns what the person typed. The `id` is one of `area`,\n `setting:<key>`, `secret:<key>`, `confirm` (`y` saves what they reviewed),\n `confirm-name` (the connection's name, typed to turn writes on), `unwrap:<key>`\n (the secret is in quotes or starts with `Bearer ` or `token `: `y` stores it\n without them, `n` as typed; call `checkSecret` first to know whether it will be\n asked), for `dossiers onboard` `create:<section>` (`y` adds the connection that\n section needs), `name:<section>` (its name) and `pin:<section>` (the matching\n connection their own copy uses), or `consent` (`yes` sends the feedback report and\n disclaimer the question shows, **Feedback**, above). A secret is checked as on a\n terminal (`checkSecret`, below), but asked once: a refused or empty required one is\n `INVALID_INPUT`, with the terminal's words. With `readOnly`, nothing is asked: `feedback`\n only previews. Return `undefined` for a question they weren't asked, and the\n command saves or sends nothing (`CANCELLED`). A secret goes from the answer to the OS\n credential store: it is never in the input, the envelope or the audit log. The\n program must ask a person and pass on their answers. Nothing about this lets an\n agent run these commands.\n- **`registry`** lists every command `execute()` serves: its name, MCP tool name,\n whether it writes to a service (`writes`) or on this machine (`writesLocal`), and\n its input's JSON Schema. It also lists the areas, each with `connection`: the\n fields `connections add` asks for, in order, each with `secret`, `password`,\n `default` and `required`.\n- **`version`** and **`contractVersion`** are what `toil version` reports. Check\n `contractVersion` before relying on anything else. `toil version` also reports\n `commit`, the 40-character hash of the commit the build came from (`null` when the\n build didn't record one), which is what a bug report from a terminal names.\n- **`mapOwi(input, options)`** maps envelopes you already hold (one, an array, or\n JSON Lines text) to Open Work Items and pull requests to changes, the way `toil\n util owi map` does (`util.md`), synchronously and without the schema check:\n `{ items, changes, histories, skipped, warnings }`. `options.fields` is a dossier\n section's `fields` object (`{ estimate: 'customfield_10234', estimateUnit: 'points' }`),\n `command` names the command for bare `data`, `key` the item a keyless history\n belongs to, `keyPatterns` where work item keys in a pull request point\n (`['PAY-{n}=corp-jira']`), and `authorKinds` the author kinds set by hand\n (`{ 'release-bot': 'BOT' }`). A refused input throws, with a fix. **`owiVersion`** is the OWI version items carry,\n and **`owiSchema`** their JSON Schema; `execute('util owi map', { text })` maps\n and validates in one call.\n- **`checkSecret(raw, rules)`** runs the paste checks `connections add` and\n `login` run on a secret, for a program whose person types one into its own field\n (Toil UI's settings): `rules` is `{ password, empty }`, `empty` being `required`,\n `keep` or `skip`. It returns `{ status: 'ok', value, length, removed, received,\n wrapper }` (`received` is the terminal's `Received 40 characters \u2026` line, and\n `wrapper`, when set, has the `question`, `what`, the value `without` it and its\n `withoutLength`), `{ status: 'refused', message, fix, length }`, or `{ status:\n 'empty', empty, message, fix }`. Nothing\n it returns holds part of the value but the value itself.\n- **`findSimilar(records, request, options)`** finds likely duplicates among OWI\n records you already hold (mapOwi's `items`, or the text `util owi map` printed),\n scored the way `toil util owi similar` scores them (`util.md`), in-process:\n `{ query }` ranks them against some text, `{ item }` against one of them by OWI\n id, and `{ pairs: true }` lists likely duplicate pairs. `options` takes\n `fields`, `limit` and `threshold`. It returns `{ mode, method, count, matches,\n pairs, search }`, each match and pair with its `score` and `why`, the same for\n the same records every time. For a very large set, use\n `execute('util owi similar', \u2026)`, which runs in a worker with a deadline.\n\nWhat `@imagile-dev/toil/api` exports, and the types it names, follow the command\ncontract: they change only additively unless `contractVersion` goes up. Anything else\nin the package is internal.\n\n## Feedback\n\n`toil feedback bug|feature` sends a bug report or a feature request to Imagile LLC,\nwhere it becomes a public GitHub issue in `imagile-dev/toil`, and the reporter is\nemailed when it's filed and when it closes. It is CLI only, never an MCP tool, and the\none request toil makes to a host you didn't configure. Every report carries this\ndisclaimer, version 1, and nothing is sent until the person sending it agrees to it:\n\n> Your report is sent to Imagile LLC to improve toil, and it becomes a public GitHub\n> issue in imagile-dev/toil. Your email address stays private: it is used only to tell\n> you about your issue. Before you send, remove company data: internal URLs and\n> hostnames, ticket keys, repository and project names, people's names, other\n> identifiers and credentials. You are responsible for what you send.\n\n```bash\ntoil feedback bug --title \"jira issue search ignores --limit\" --body \"toil jira issue search --limit 5 returns 50 issues.\" --email you@example.com\n```\n\n| Flag | Meaning |\n|------|---------|\n| `--title <text>` | One line, up to 120 characters |\n| `--body <text>` | The details, up to 4000 characters |\n| `--email <address>` | The reporter's own address, kept private |\n| `--input-file <file>` | JSON with any of `kind`, `title`, `body` and `email`, for long text; a flag beats the file, and `-` reads stdin |\n| `--consent` | Send it. Without it nothing is sent |\n\nWithout `--consent`, the command sends nothing. On a terminal it shows the report and\nthe disclaimer and asks; anywhere else it returns `sent: false`, the exact `report`\nit would send, the `disclaimer`, `consentVersion` and how to approve, with a\n`FEEDBACK_NOT_SENT` warning. With `--consent` it sends that same report and returns\n`sent: true` and the endpoint's message. The report is the kind, title, body and email\ngiven, plus `version`, `commit` and `consent` (the disclaimer's version). toil never\nadds config, connection names, hosts or tokens. A build that doesn't know its commit\npreviews but can't send (`UNSUPPORTED`); the form at\nhttps://imagile-dev.github.io/toil/feedback/ works from any browser.\n\n**An agent sending feedback for a user follows every step, in order, every time:**\n\n1. **Only when the user asks.** Never offer to send a report on your own initiative,\n and never send one because a command failed.\n2. **Scrub it.** Replace company data with neutral placeholders before the user sees\n the draft: internal URLs and hostnames (`jira.imagile.dev`), ticket keys\n (`PROJ-123`), repository, project and team names (`my-repo`), people's names\n (`a colleague`), email addresses other than the reporter's own, IDs, tokens,\n passwords and anything else credential-shaped. Keep toil's own command names,\n flags and error codes; they're what makes a report useful.\n3. **Show it.** Run the command without `--consent` and show the user the full\n `data.report` it returned, and the `data.disclaimer`, word for word.\n4. **Ask.** Get the user's explicit yes in chat to sending that exact report. A yes to\n an earlier draft, or to feedback in general, isn't one.\n5. **Send it.** Only then run the same command again with `--consent`, unchanged. If\n the user asks for any change, make it, and go back to step 3.\n\nThrough `@imagile-dev/toil/api`, `feedback` runs only for a `person` (below), whose\n`yes` to the `consent` question sends it; the `consent` field is refused there, and a\n`readOnly` call only previews. `TOIL_FEEDBACK_URL` points the command at a local copy\nof the feedback function for testing, and takes only a loopback address\n(`http://127.0.0.1:7071`).\n\n## Certificates and proxies\n\ntoil trusts the OS certificate store and Node's bundled CAs, and uses `HTTPS_PROXY` /\n`HTTP_PROXY` / `NO_PROXY` when they're set. A `NETWORK` error about an untrusted\ncertificate means the CA is in neither; `NODE_EXTRA_CA_CERTS` adds it.\n",
140328
140431
  "db.md": '---\narea: db\ndescription: Schemas, tables, describe, row previews, read-only queries with paging, and gated writes on databases (SQLite, PostgreSQL, MySQL/MariaDB, SQL Server, Oracle)\n---\n\n# Databases (`db`)\n\nOne set of commands for every database engine. Each connection says which engine it\nuses, and the commands work the same way on all of them.\n\n| Engine | `engine` value | Status |\n|--------|----------------|--------|\n| SQLite | `sqlite` | `live`: automated tests run against the real engine (Node\'s built-in `node:sqlite`) |\n| PostgreSQL | `postgres` | `live`: automated tests run against PostgreSQL 17 (the official `postgres:17` image) |\n| MySQL / MariaDB | `mysql` | `live`: automated tests run against MySQL 8.4 and MariaDB 11.8 (the official `mysql:8.4` and `mariadb:11.8` images) |\n| SQL Server | `sqlserver` | `live`: automated tests run against SQL Server 2022 (the official `mcr.microsoft.com/mssql/server:2022-CU27-ubuntu-22.04` image) |\n| Oracle | `oracle` | `live`: automated tests run against Oracle Database 23ai Free (the `gvenzl/oracle-free:23.26.3-slim-faststart` image) |\n\n**Supported versions:** The oldest SQLite version toil supports hasn\'t been established. toil\nuses the SQLite built into Node, so the version is whichever your Node ships.\nPostgreSQL is tested against 17; the catalog columns toil reads need 11 or later.\nMySQL is tested against 8.4 and MariaDB against 11.8; the oldest versions toil\nsupports haven\'t been established.\nSQL Server is tested against 2022; the catalog views and `OFFSET ... FETCH` toil uses\nneed 2012 or later. Azure SQL Database speaks the same protocol but hasn\'t been tested.\nOracle is tested against 23ai; Thin mode and the dictionary columns toil reads need\n12.1 or later. No release older than 23ai has been run.\n\n## SQLite connections\n\nThere is nothing to install: toil uses the SQLite built into Node.\n\n| Key | Required | Meaning |\n|-----|----------|---------|\n| `engine` | yes | `sqlite` |\n| `path` | yes | Absolute path to an existing database file. toil never creates one. |\n| `writes` | no | `true` lets `db execute` change data on this connection. Off by default. |\n\n**Environment variables**, for the default `db` connection:\n\n```bash\nexport TOIL_DB_ENGINE=sqlite\nexport TOIL_DB_PATH=/srv/data/app.db\n# Only if this connection may be written to:\nexport TOIL_DB_WRITES=true\n```\n\nA named connection, defined entirely from the environment (handy in CI):\n\n```bash\nexport TOIL_CONN_SCRATCH_AREA=db\nexport TOIL_CONN_SCRATCH_ENGINE=sqlite\nexport TOIL_CONN_SCRATCH_PATH=/tmp/scratch.db\nexport TOIL_CONN_SCRATCH_WRITES=true\n```\n\n**Config file** (`~/.toil/config.json`), with a read-only connection as the default\nand a writable scratch copy beside it:\n\n```json\n{\n "version": 2,\n "connections": {\n "app": { "area": "db", "engine": "sqlite", "path": "/srv/data/app.db" },\n "scratch": { "area": "db", "engine": "sqlite", "path": "/tmp/scratch.db", "writes": true }\n },\n "defaults": { "db": { "connection": "app" } }\n}\n```\n\nOn Windows, write the path with forward slashes or escaped backslashes in JSON:\n`"C:/data/app.db"`.\n\n## PostgreSQL connections\n\ntoil speaks PostgreSQL\'s wire protocol in plain JavaScript (the `pg` driver, bundled\ninto toil): no libpq, no `psql`, nothing to install.\n\n| Key | Required | Meaning |\n|-----|----------|---------|\n| `engine` | yes | `postgres` |\n| `host` | yes | Server host name or address |\n| `port` | no | TCP port. Default `5432`. |\n| `database` | yes | The database to connect to |\n| `user` | yes | The login role |\n| `password` | no | The role\'s password. A secret: an env var or the OS credential store, never the config file. |\n| `ssl` | no | `true` connects over TLS and verifies the server\'s certificate against Node\'s CAs, `NODE_EXTRA_CA_CERTS` and the OS certificate store, so a corporate root in the OS store is trusted. Off by default. |\n| `writes` | no | `true` lets `db execute` change data on this connection. Off by default. |\n\n**Environment variables**, for the default `db` connection:\n\n```bash\nexport TOIL_DB_ENGINE=postgres\nexport TOIL_DB_HOST=db.imagile.dev\nexport TOIL_DB_PORT=5432\nexport TOIL_DB_DATABASE=app\nexport TOIL_DB_USER=reader\nexport TOIL_DB_PASSWORD=<the role\'s password>\nexport TOIL_DB_SSL=true\n```\n\nOr keep the connection in config and the password in the OS credential store:\n\n```json\n{\n "version": 2,\n "connections": {\n "app-pg": { "area": "db", "engine": "postgres", "host": "db.imagile.dev", "database": "app", "user": "reader", "ssl": true }\n },\n "defaults": { "db": { "connection": "app-pg" } }\n}\n```\n\n```bash\ntoil connections login app-pg # prompts for the password and stores it\n```\n\nA named connection\'s password can also come from `TOIL_CONN_APP_PG_PASSWORD`.\n\ntoil ignores the libpq environment (`PGHOST`, `PGUSER`, `PGPASSWORD`, `PGSSLMODE`,\n`PGOPTIONS` and the rest) and `~/.pgpass`: a connection reaches only the host its own\nsettings name, with only its own password.\n\n**Connect with an ordinary role** that can read what the agent should see, ideally\none with only `SELECT` grants. See the known limit under "Reads are read-only at the\nengine".\n\n## MySQL and MariaDB connections\n\nOne engine, `mysql`, covers both. toil speaks their wire protocol in plain\nJavaScript (the `mysql2` driver, bundled into toil): no client library, no `mysql`\nCLI, nothing to install.\n\n| Key | Required | Meaning |\n|-----|----------|---------|\n| `engine` | yes | `mysql` |\n| `host` | yes | Server host name or address |\n| `port` | no | TCP port. Default `3306`. |\n| `database` | yes | The database to connect to. It is also the default schema. |\n| `user` | yes | The account |\n| `password` | no | The account\'s password. A secret: an env var or the OS credential store, never the config file. |\n| `ssl` | no | `true` connects over TLS and verifies the server\'s certificate and host name against Node\'s and the OS\'s certificate stores. Off by default. |\n| `writes` | no | `true` lets `db execute` change data on this connection. Off by default. |\n\n**Environment variables**, for the default `db` connection:\n\n```bash\nexport TOIL_DB_ENGINE=mysql\nexport TOIL_DB_HOST=db.imagile.dev\nexport TOIL_DB_PORT=3306\nexport TOIL_DB_DATABASE=app\nexport TOIL_DB_USER=reader\nexport TOIL_DB_PASSWORD=<the account\'s password>\nexport TOIL_DB_SSL=true\n```\n\nOr in config, with the password in the OS credential store:\n\n```json\n{\n "version": 2,\n "connections": {\n "app-mysql": { "area": "db", "engine": "mysql", "host": "db.imagile.dev", "database": "app", "user": "reader", "ssl": true }\n },\n "defaults": { "db": { "connection": "app-mysql" } }\n}\n```\n\n```bash\ntoil connections login app-mysql # prompts for the password and stores it\n```\n\ntoil reads no option file (`my.cnf`, `~/.mylogin.cnf`) and no `MYSQL_*` variable. It\nnever sends the password in clear text (an account using `mysql_clear_password`\nfails with `AUTH`), and it never uploads a local file: `LOAD DATA LOCAL` is off.\n\n**Connect with an account that has only `SELECT`** on what the agent should see. See\nthe known limits under "Reads are read-only at the engine".\n\n## SQL Server connections\n\ntoil speaks TDS, SQL Server\'s wire protocol, in plain JavaScript (the `tedious`\ndriver, bundled into toil): no ODBC driver, no `sqlcmd`, nothing to install. It signs\nin with a SQL Server login (user name and password), which needs the server to allow\nSQL Server authentication (mixed mode), or, on Windows only, with Windows\nauthentication (`"auth": "windows"`, below).\n\n| Key | Required | Meaning |\n|-----|----------|---------|\n| `engine` | yes | `sqlserver` |\n| `host` | yes | Server host name or address |\n| `port` | no | TCP port. Default `1433`. A named instance needs its own port here: toil doesn\'t ask the SQL Browser service. |\n| `database` | yes | The database to connect to |\n| `user` | for a SQL login | The SQL Server login; with `"auth": "windows"`, another domain account to sign in as |\n| `password` | no | The login\'s password. A secret: an env var or the OS credential store, never the config file. |\n| `ssl` | no | `true` encrypts the connection with TLS and verifies the server\'s certificate against the OS certificate store. Off by default, which sends the login and every result unencrypted, so turn it on unless the network is trusted. There is no setting to trust any certificate: add the server\'s certificate, or your organization\'s CA, to the OS store instead. |\n| `auth` | no | `sql` (a SQL Server login, the default) or `windows` (Windows authentication, Windows only) |\n| `domain` | no | With `"auth": "windows"` and `user`: the account\'s domain |\n| `writes` | no | `true` lets `db execute` change data on this connection. Off by default. |\n\n**Environment variables**, for the default `db` connection:\n\n```bash\nexport TOIL_DB_ENGINE=sqlserver\nexport TOIL_DB_HOST=sql.imagile.dev\nexport TOIL_DB_PORT=1433\nexport TOIL_DB_DATABASE=app\nexport TOIL_DB_USER=toil_reader\nexport TOIL_DB_PASSWORD=<the login\'s password>\nexport TOIL_DB_SSL=true\n```\n\nOr keep the connection in config and the password in the OS credential store:\n\n```json\n{\n "version": 2,\n "connections": {\n "app-sql": { "area": "db", "engine": "sqlserver", "host": "sql.imagile.dev", "database": "app", "user": "toil_reader", "ssl": true }\n },\n "defaults": { "db": { "connection": "app-sql" } }\n}\n```\n\n```bash\ntoil connections login app-sql # prompts for the password and stores it\n```\n\nA named connection\'s password can also come from `TOIL_CONN_APP_SQL_PASSWORD`.\n\n### Windows authentication (Windows only)\n\n`"auth": "windows"` signs in as the Windows user running toil, with no password\nstored anywhere: Windows proves who you are with the Kerberos ticket (or NTLM) it\nalready holds from your logon.\n\n```json\n{\n "version": 2,\n "connections": {\n "app-sql": { "area": "db", "engine": "sqlserver", "host": "sql.imagile.dev", "database": "app", "auth": "windows", "ssl": true }\n }\n}\n```\n\nFrom the environment, for the default `db` connection, as the current Windows user:\n\n```bash\nexport TOIL_DB_ENGINE=sqlserver\nexport TOIL_DB_HOST=sql.imagile.dev\nexport TOIL_DB_DATABASE=app\nexport TOIL_DB_AUTH=windows\n```\n\nTo sign in as a different domain account, add `domain` and `user` (`TOIL_DB_DOMAIN`,\n`TOIL_DB_USER`), and store that account\'s password with `toil connections login\napp-sql` (Windows Credential Manager), or set `TOIL_CONN_APP_SQL_PASSWORD`.\n\n| Platform | `"auth": "windows"` |\n|----------|---------------------|\n| Windows | Supported |\n| macOS, Linux | Refused before connecting (`CONFIG_INVALID`); use a SQL Server login |\n\nHow it works: Node has no way to ask Windows for a sign-in token, so for each\nconnection toil runs one Windows PowerShell (`powershell.exe` from the Windows\nfolder, `-NoProfile -NonInteractive`), which asks Windows\' SSPI `Negotiate` package\nfor tokens for the server\'s SPN, `MSSQLSvc/<host>:<port>`. The script and every token\npass over the process\'s stdin and stdout, never its command line. Use the server\'s\nfully qualified name in `host`, the name its SPN is registered under; with any other\nname Kerberos can\'t find the SPN, and Windows falls back to NTLM if the server and\ndomain allow it.\n\nWindows PowerShell must run in Full Language mode. Where an AppLocker or WDAC\npolicy puts it in Constrained Language mode, `Add-Type` is blocked, and toil says so\nwith `AUTH` naming the mode instead of failing the login vaguely. Windows PowerShell\n5.1\'s `Add-Type` also compiles a small helper with `csc.exe` into `TEMP`, so `TEMP`\nmust be writable.\n\nWindows authentication is `untested` against a real server: its tests run the\nhelper against Windows\' own SSPI, and a full multi-step handshake completes, but\nno run against SQL Server on a domain has happened yet, nor one under a\nConstrained Language Mode policy.\n\n**Connect with a read-only login.** SQL Server has no read-only transaction, so toil\ncan\'t ask the server to refuse writes the way it does for PostgreSQL. It rolls back\nevery read instead (see "Reads are read-only at the engine"), and the login is what\nmakes the server itself refuse a write. A login whose database user is only in\n`db_datareader` is enough:\n\n```sql\nCREATE LOGIN toil_reader WITH PASSWORD = \'<a strong password>\';\nUSE app;\nCREATE USER toil_reader FOR LOGIN toil_reader;\nALTER ROLE db_datareader ADD MEMBER toil_reader;\n```\n\nUse a second connection, with a login that may write and `writes: true`, for `db\nexecute`.\n\n## Oracle connections\n\ntoil speaks Oracle Net in plain JavaScript (the `oracledb` driver in Thin mode, bundled\ninto toil): no Instant Client, no `sqlplus`, no native library, nothing to install.\ntoil never switches the driver to Thick mode.\n\n| Key | Required | Meaning |\n|-----|----------|---------|\n| `engine` | yes | `oracle` |\n| `host` | yes | Listener host name or IP address. Nothing else: no port, scheme or descriptor. |\n| `port` | no | Listener port. Default `1521`. |\n| `database` | yes | The **service name** (`FREEPDB1`, `ORCLPDB1`). Not a SID, and not a TNS alias. |\n| `user` | yes | The user. Unquoted, it\'s read in upper case, as Oracle does; wrap it in double quotes for a case-sensitive one. |\n| `password` | no | The user\'s password. A secret: an env var or the OS credential store, never the config file. |\n| `ssl` | no | `true` connects over TCPS and verifies the server\'s certificate, and that its name matches `host`, against the OS certificate store. Off by default. |\n| `writes` | no | `true` lets `db execute` change data on this connection. Off by default. |\n\n```bash\nexport TOIL_DB_ENGINE=oracle\nexport TOIL_DB_HOST=db.imagile.dev\nexport TOIL_DB_PORT=1521\nexport TOIL_DB_DATABASE=ORCLPDB1\nexport TOIL_DB_USER=reader\nexport TOIL_DB_PASSWORD=<the user\'s password>\n```\n\n```json\n{\n "version": 2,\n "connections": {\n "app-ora": { "area": "db", "engine": "oracle", "host": "db.imagile.dev", "database": "ORCLPDB1", "user": "reader" }\n },\n "defaults": { "db": { "connection": "app-ora" } }\n}\n```\n\n```bash\ntoil connections login app-ora # prompts for the password and stores it\n```\n\ntoil builds the connect descriptor itself from `host`, `port` and `database`, so it\nreads no `tnsnames.ora`, `sqlnet.ora`, `TNS_ADMIN` or wallet. Thin mode needs the\nuser\'s password to have an 11G or 12C verifier; an older one fails with `AUTH`,\nsaying so.\n\n**Connect with a read-only account**: a user granted `SELECT` (or `READ`) on what the\nagent should see, and nothing that writes. On Oracle this matters more than on the\nother engines; see the known limit under "Reads are read-only at the engine".\n\n## Commands\n\n| Command | MCP tool | Returns |\n|---------|----------|---------|\n| `toil db schema list` | `db_schema_list` | `{ schemas: [{ name }] }`. For SQLite, the attached databases (`main`); for PostgreSQL, the schemas, without `pg_*` and `information_schema`; for MySQL, the databases the account can see, without `mysql`, `sys`, `performance_schema` and `information_schema`; for SQL Server, the schemas, without `sys`, `INFORMATION_SCHEMA`, `guest` and the `db_*` role schemas; for Oracle, the users the login can see that Oracle doesn\'t maintain. |\n| `toil db table list [--schema <name>]` | `db_table_list` | `{ schema, tables: [{ name, type }] }`, `type` being `table` or `view` |\n| `toil db table describe <table> [--schema <name>]` | `db_table_describe` | `{ schema, name, type, columns, primaryKey, indexes, foreignKeys }` |\n| `toil db table preview <table> [--schema] [--limit] [--cursor]` | `db_table_preview` | A page of rows: `{ columns, rows }` |\n| `toil db query <sql> [--limit] [--cursor] [--no-lint]` | `db_query` | A page of rows from one read-only statement: `{ columns, rows }` |\n| `toil db execute <sql> --allow-write [--no-lint]` | `db_execute` | `{ changes }`: rows inserted, updated or deleted |\n| `toil db lint <sql> [--engine <engine>] [--as <command>]` | `db_lint` | `{ engine, as, errors, warnings, findings }`: what the pre-flight lint finds in the SQL, without running it |\n\nEvery command takes `--connection <name>`. `--schema` defaults to the engine\'s\ndefault schema (`main` for SQLite, `public` for PostgreSQL, the connection\'s database\nfor MySQL, where a schema is a database, `dbo` for SQL Server, and the user\'s own\nschema for Oracle). PostgreSQL names are case-sensitive as stored: an unquoted\n`CREATE TABLE People` is stored as `people`. MySQL table names are case-sensitive on\nmost Linux servers. Oracle stores an unquoted name in upper case and reports names as\nstored (`PEOPLE`, `ID`); a schema or table you name that doesn\'t exist as written is\nlooked up again in upper case, so `table describe people` finds `PEOPLE`. A quoted\nmixed-case name (`"People"`) must be typed exactly.\n\nRows come back as arrays in the order of `columns`, so a join\'s two `id` columns both\nsurvive:\n\n```json\n{ "columns": [{ "name": "id", "type": "INTEGER" }, { "name": "name", "type": "TEXT" }],\n "rows": [[1, "Ada"], [2, "Grace"]] }\n```\n\n`type` is the column\'s declared type, or null for an expression. Integers too large\nfor JavaScript come back as strings, and binary values as base64.\n\nPostgreSQL names every result column\'s type (`integer`, `character varying(100)`,\n`timestamp with time zone`). `numeric` comes back as a string, so no digits are lost;\n`json` and `jsonb` as JSON; arrays as arrays. Dates, times, timestamps and intervals\ncome back as the text the server sent, never shifted into the local time zone.\n\nMySQL names each result column\'s type from the protocol (`INT`, `BIGINT`, `VARCHAR`,\n`DECIMAL`, `DATETIME`), without lengths; `table describe` gives the full column type\n(`varchar(100)`). `DECIMAL` comes back as a string; dates, times and timestamps as the\ntext the server sent; `JSON` as JSON; `BLOB`, `BINARY` and `BIT` as base64.\n`table preview` orders a table by its primary key, so pages stay stable. In\n`table describe`, a foreign key\'s `NO ACTION` and `RESTRICT` both read as null: InnoDB\nenforces them the same way, and MariaDB reports an unstated rule as `RESTRICT`.\nSQL Server names every result column\'s type as you\'d write it in DDL (`int`,\n`varchar(100)`, `nvarchar(max)`, `decimal(10,2)`, `datetime2(7)`). `bigint` comes back\nas a number when it fits and a string when it doesn\'t; `bit` as true or false;\n`uniqueidentifier` as a string; binary as base64. `date`, `time`, `datetime`,\n`datetime2` and `smalldatetime` come back as the text of the value the server holds,\nnever shifted into a time zone (`2026-01-02 03:04:05.123`), to the millisecond: digits\npast that are dropped. `datetimeoffset` comes back as the instant in UTC\n(`2026-01-02T01:04:05.000Z`), without its original offset. `decimal`, `numeric` and\n`money` come back as JSON numbers, so a value with more than about 15 significant\ndigits loses the rest; `CAST` it to `varchar` in the query when every digit matters.\n`table preview` pages in primary-key order, or in the engine\'s own order for a table\nwithout one.\n\nOracle names each result column\'s type (`NUMBER`, `VARCHAR2`, `DATE`), and\n`table describe` gives the declared form (`NUMBER(10,2)`, `VARCHAR2(100)`). A `NUMBER`\nis a JSON number when that\'s exactly its value, and a string otherwise, so no digits\nare lost. `CLOB` comes back as text, `BLOB` and `RAW` as base64, `BOOLEAN` as a\nboolean, and `BINARY_DOUBLE`\'s NaN and infinities as strings. Dates and\ntimestamps come back exactly as stored, in the shape PostgreSQL and MySQL use, never\nthrough the local time zone of the machine running toil: `DATE` as\n`2026-01-02 03:04:05`, `TIMESTAMP` with every fractional digit it holds\n(`2026-01-02 03:04:05.123456`), and `TIMESTAMP WITH TIME ZONE` with its offset\n(`2026-01-02 03:04:05+02`, `+05:30`). A value stored with a named region\n(`Europe/Paris`) and `TIMESTAMP WITH LOCAL TIME ZONE` come back as the same instant in\nUTC (`+00`).\n\n### Paging and row caps\n\n`table preview` and `query` return 100 rows per page unless you pass `--limit`\n(1 to 1000). When there are more, `meta.page.nextCursor` holds a cursor; pass it\nback with `--cursor`, along with the same SQL or table, to get the next page. A\ncursor only works with the query it came from. Use `ORDER BY` in a query you page\nthrough, so the pages are stable.\n\n### Pre-flight lint\n\nBefore `db query` or `db execute` sends anything, toil checks the SQL against the\nconnection\'s engine, with no network and no model. An **error** refuses the\nstatement before a connection is even opened, with a fix in that engine\'s own form;\na **warning** lets it run and lands in `meta.warnings` (code `LINT`). `meta.lint`\nnames the engine and every rule that ran, on success and failure alike.\n\n| Rule | Severity | Engines | Trips on |\n|------|----------|---------|----------|\n| `unterminated` | error | all | A string, quoted name or block comment that is never closed (SQLite lets a block comment run to the end, so only its strings and names) |\n| `multiple-statements` | error | all but SQL Server, on `db query` | More than one statement. SQL Server is left to its own check, which refuses SQL that returns more than one result, so `DECLARE @n int = 1; SELECT @n` still runs |\n| `read-only-write` | error (`WRITE_DISABLED`) | all, on `db query` | A statement that starts with `INSERT`, `UPDATE`, `DELETE`, `MERGE`, `REPLACE`, `CREATE`, `ALTER`, `DROP`, `TRUNCATE`, `GRANT`, `REVOKE`, `RENAME` or `COMMENT`, or a `WITH` holding a data change |\n| `dialect-limit` | error | SQL Server, Oracle | `LIMIT n`: use `TOP (n)` or `OFFSET ... FETCH NEXT n ROWS ONLY` on SQL Server, `FETCH FIRST n ROWS ONLY` on Oracle (`ROWNUM <= n` on 11g). A PL/SQL block\'s own `BULK COLLECT ... LIMIT n` is left alone |\n| `dialect-top` | error | all but SQL Server | `SELECT TOP n`: use `LIMIT n`, or `FETCH FIRST n ROWS ONLY` on Oracle |\n| `dialect-backtick` | error; warning on SQLite | all but MySQL | `` `name` ``: use `"name"`, or `[name]` on SQL Server. SQLite accepts backticks for MySQL compatibility, so there it only warns |\n| `dialect-function` | warning | all | A function another engine has: `NOW()`, `GETDATE()`, `SYSDATETIME()`, two-argument `ISNULL()`, `NVL()`, `IFNULL()`, `LEN()`, `LENGTH()`, `CHARINDEX()`, `SUBSTR()`, where the engine lacks it |\n| `dialect-concat` | warning | all | `\\|\\|` on SQL Server (use `+` or `CONCAT()`) or MySQL (a logical OR there; use `CONCAT()`), and `+` beside a text literal elsewhere (use `\\|\\|`, or `CONCAT()` on MySQL) |\n| `select-star` | warning | all, on `db query` | `SELECT *` at the top of a query, whose rows are capped at `--limit` |\n| `implicit-cross-join` | warning | all | A comma between tables in `FROM` with no `WHERE`, which pairs every row with every row |\n\nEvery finding has its rule, a message, a fix, and its position in the SQL: `offset`\nfrom the start, and 1-based `line` and `column`. An error\'s `error.details.lint`\nlists them.\n\n`--no-lint` (`lint: false` over MCP) skips the warnings for one call. Errors always\nrun: `--no-lint` can\'t send a write through `db query`, and it can\'t send SQL the\nengine would refuse anyway.\n\n`toil db lint <sql>` runs the same lint without running anything, and returns the\nfindings as `data`. With `--engine`, it uses no connection at all: none is looked up\nand no secret is read, so it works with nothing set up. Without it, it takes the\nengine from the connection. `--as execute` checks the SQL as `db execute` would (a\nscript of changes) instead of as `db query` would (the default).\n\n```bash\ntoil db lint "SELECT TOP 10 * FROM people" --engine postgres\n```\n\nThe lint is a check, not a guard. It refuses a write on `db query` a little earlier,\nbut what keeps a read read-only is the engine, below, and that still holds for any\nSQL the lint lets through. A table\'s size isn\'t known locally, so the lint has no\nrule for a missing `WHERE` on a large table.\n\n### Reads are read-only at the engine\n\n`db query`, `table preview` and the listing commands open SQLite read-only with\n`PRAGMA query_only` on. A statement that tries to write fails with `WRITE_DISABLED`,\nwhatever the connection\'s `writes` setting. `db query` runs exactly one statement;\nSQL holding several is refused with `INVALID_INPUT`.\n\n`VACUUM` is refused on every read with `INVALID_INPUT`, before it reaches SQLite.\n`VACUUM INTO \'<file>\'` creates its target file even on a read-only connection, so\nreads never get the chance. To vacuum or to write a copy, use `db execute` with\nwrites on; it runs a lone `VACUUM` outside the usual transaction, because SQLite\ncan\'t vacuum inside one, and refuses `VACUUM` mixed with other statements.\n\nOne known gap remains: `ATTACH DATABASE` from a read-only query can open another\nexisting SQLite file for reading (it can\'t create one). If the files a connection\ncan reach matter, run toil as a user that can read only what it should.\n\n**PostgreSQL** runs every read in a transaction begun with `SET TRANSACTION READ ONLY`\nand rolled back, on a connection opened for that one call. The server refuses any\nwrite (`INSERT`, `UPDATE`, DDL, `nextval`, a data-modifying `WITH`) with SQLSTATE\n25006, which comes back as `WRITE_DISABLED`. `db query` sends its statement on the\nextended protocol, which refuses a second one, so several statements are\n`INVALID_INPUT` here too.\n\n`COPY` and `DO` are refused on every read with `INVALID_INPUT`, before they reach the\nserver: `COPY ... TO \'<file>\'` writes a file on the server, and `TO PROGRAM` runs one,\neven in a read-only transaction, for a role allowed to, and a `DO` block can run the\nsame `COPY`. Neither returns rows a query could page. To run them, use `db execute`.\n\nKnown limit: functions with effects outside the database still run in a read-only\ntransaction for a role allowed to call them. `lo_export` writes a server file,\n`pg_terminate_backend` ends sessions, `pg_reload_conf` reloads the server\'s config,\nand an extension such as `dblink` can reach another database. They can\'t be refused\nby name, so connect with an ordinary role: not a superuser, and not a member of\n`pg_write_server_files`, `pg_execute_server_program` or `pg_signal_backend`.\n\n**MySQL and MariaDB** run every read on a session set to `SET SESSION TRANSACTION READ\nONLY`, inside `START TRANSACTION READ ONLY`, rolled back, on a connection opened for\nthat one call. Both are needed: DDL commits the transaction implicitly, and the session\nsetting makes the server refuse it all the same. Any write (`INSERT`, `UPDATE`, DDL,\n`LOAD DATA`) fails with error 1792, which comes back as `WRITE_DISABLED`. `db query`\nsends one statement with multi-statements off; several are `INVALID_INPUT`.\n\n`SELECT ... INTO OUTFILE`, `INTO DUMPFILE` and every `SET` are refused on reads with\n`INVALID_INPUT`, before they reach the server: `INTO OUTFILE` writes a server file even\nin a read-only transaction, for an account with `FILE`, and `SET GLOBAL` or `SET\nPERSIST` changes the server\'s configuration. To run them, use `db execute`.\n\nKnown limits: a stored procedure that commits and switches its own session to read-write\ncan still write when a read `CALL`s it, and administrative statements that aren\'t\nwrites (`KILL`, `FLUSH`, `SHUTDOWN`) run for an account allowed to. Neither can be\nrefused by name without refusing ordinary reads, so connect with an account that has\n`SELECT` only: no `FILE`, `SUPER`, `SYSTEM_VARIABLES_ADMIN` or `CONNECTION_ADMIN`, and no\n`EXECUTE` on procedures that change data.\n**SQL Server** has no read-only transaction. toil runs every read in a transaction,\non a connection opened for that one call, and always rolls it back, so nothing a read\ndoes is kept. The server reports the type of every statement it runs, and a read whose\nstatement the server reports as changing data or schema (`INSERT`, `UPDATE`,\n`DELETE`, `MERGE`, `SELECT INTO`, `CREATE`, `ALTER`, `DROP`, `TRUNCATE`, `UPDATE\nSTATISTICS`, including inside `EXEC`) comes back as `WRITE_DISABLED`. With a\nread-only login the server refuses the write itself, which comes back as\n`WRITE_DISABLED` too. `db query` returns one result: SQL that returns a second result\nis `INVALID_INPUT`. When the first result fills the page, toil stops the batch there\nwith a TDS attention, so anything after it in the same SQL never runs.\n\n`COMMIT`, `ROLLBACK`, `BEGIN TRANSACTION` and `SAVE TRANSACTION` are refused on every\nread with `INVALID_INPUT`, before they reach the server: a `COMMIT` would end the\ntransaction toil rolls back, and keep the write before it. An `OUTPUT` clause is refused\non reads too: an `INSERT`, `UPDATE`, `DELETE` or `MERGE` with `OUTPUT` sends its rows\nbefore the server reports the change, so a full page could stop it before toil learns it\nwas a write. A column or alias named `output` in a plain `SELECT` is fine; in SQL that\nalso holds one of those words, bracket-quote it as `[output]`. A read-only login\'s refusal of a permission that only reads (a `sys.dm_db_*`\nview needing `VIEW DATABASE STATE`, `SHOWPLAN`) comes back as `DATABASE`, naming the\npermission.\n\nKnown limit: transaction control inside dynamic SQL or a procedure (an `EXEC` whose\ntext holds a `COMMIT`) can\'t be refused by name, and neither can an `OUTPUT` clause\nthere (`EXEC(\'UPDATE ... OUTPUT ...\')`): its changed rows can fill a page and come back\nas an ordinary result, though the change is still rolled back. A write under `SET\nNOCOUNT ON` isn\'t reported by the server. toil notices the transaction ending and says so with\n`DATABASE` ("anything it changed may have been saved"), but by then the change is\nmade. That is why a SQL Server connection for reads should use a read-only login:\nwith one, the server refuses the write whatever the SQL does.\n\n**Oracle** runs every read in a transaction begun with `SET TRANSACTION READ ONLY` and\nrolled back, on a connection opened for that one call. The server refuses `INSERT`,\n`UPDATE`, `DELETE`, `MERGE` and `SELECT ... FOR UPDATE` with ORA-01456, which comes\nback as `WRITE_DISABLED`, as do a read-only user or session (ORA-28193) and a database\nopen read-only (ORA-16000). `db query` runs one statement; several are `INVALID_INPUT`.\n\nThat transaction doesn\'t hold everything, so some statements are refused on every read\nbefore they reach the server:\n\n- **DDL** (`CREATE`, `ALTER`, `DROP`, `TRUNCATE`, `RENAME`, `GRANT`, `REVOKE`,\n `COMMENT`, `ANALYZE`, `PURGE`, `FLASHBACK`, `NOAUDIT`, `ASSOCIATE`,\n `DISASSOCIATE`) is `WRITE_DISABLED`: Oracle commits before and after DDL, so it runs,\n and stays, inside a read-only transaction.\n- **PL/SQL** (`BEGIN`, `DECLARE`, `CALL`, and `WITH FUNCTION` or `WITH PROCEDURE`) is\n `INVALID_INPUT`: a block can `COMMIT`, `EXECUTE IMMEDIATE` DDL, or run an autonomous\n transaction, and `CALL` reaches built-ins such as `DBMS_UTILITY.EXEC_DDL_STATEMENT`.\n\nTo run any of them, use `db execute`.\n\nKnown limit: a stored function that runs an autonomous transaction (`PRAGMA\nAUTONOMOUS_TRANSACTION`) still writes when a `SELECT` calls it, and a function can\'t be\nrefused by name. **Connect with an account that can\'t write**: then nothing a query\ncalls can either. `AUDIT` isn\'t refused either: it needs the audit privileges an\nordinary account doesn\'t have. A trigger or stored function with an autonomous\ntransaction commits on its own; toil can\'t see it, so "nothing was applied" after a\nfailed `db execute` covers only the script\'s own transaction.\n\n### Writes\n\n`db execute` is the only command that changes data. It needs both:\n\n1. `writes: true` on the connection (`TOIL_DB_WRITES=true`, or\n `TOIL_CONN_<NAME>_WRITES=true`), set by the person who owns the config, and\n2. `--allow-write` on the call (`allowWrite: true` over MCP).\n\nWithout either it fails with `WRITE_DISABLED` and changes nothing. It runs one or more\nstatements, separated by semicolons, in one transaction that commits only if every\nstatement succeeds. A script that starts or ends a transaction of its own (`BEGIN`,\n`COMMIT`, `END`, `ROLLBACK`, `SAVEPOINT`, `RELEASE`, and for PostgreSQL also `START`,\n`ABORT` and `PREPARE TRANSACTION`; for MySQL also `START TRANSACTION`, `XA`, `LOCK` and\n`UNLOCK TABLES`, and `SET autocommit`) is refused with `INVALID_INPUT` before any of it runs.\n\nOn MySQL and MariaDB, DDL (`CREATE`, `ALTER`, `DROP`, `TRUNCATE`) commits implicitly,\nso a script holding DDL isn\'t all or nothing: what ran before the DDL is committed\neven if a later statement fails. Keep DDL in a script of its own. A server running\n`read_only`, or an account whose transactions default to read-only, fails writes with\n`DATABASE`, saying so.\nOn SQL Server that means `BEGIN TRANSACTION`, `COMMIT`, `ROLLBACK` and `SAVE\nTRANSACTION`; `BEGIN ... END` blocks, `TRY ... CATCH` and `CASE` are fine. A SQL\nServer script runs as one batch, so leave out `GO`, and a statement that must start a\nbatch (`CREATE VIEW`, `CREATE PROCEDURE`) goes in a call of its own. `changes` counts\nthe rows `INSERT`, `UPDATE`, `DELETE`, `MERGE` and `SELECT INTO` reported; under `SET\nNOCOUNT ON` the server reports none.\n\nOn PostgreSQL, statements that can\'t run inside a transaction (`VACUUM`, `CREATE\nDATABASE`, `CREATE INDEX CONCURRENTLY`) fail with `DATABASE`; run those with your own\ntools. A connection that reaches a read-only standby, or a role whose transactions\ndefault to read-only, fails writes with `DATABASE`, saying so.\n\nOn Oracle, a script\'s statements are separated by semicolons, and a PL/SQL unit (a\n`BEGIN` or `DECLARE` block, `CREATE FUNCTION`, `PROCEDURE`, `PACKAGE`, `TRIGGER` or\n`TYPE`) runs to a line holding only `/`, as in SQL*Plus, or to the end of the script.\n`COMMIT`, `ROLLBACK`, `SAVEPOINT` and `SET TRANSACTION` are refused before any of it\nruns. Two things Oracle does break all-or-nothing, and toil can\'t stop them: **DDL\ncommits** everything before it, and itself, as it runs, and a PL/SQL block can commit\ninside. When a script fails after Oracle has committed part of it (a DDL statement\nthat ran, or failed after parsing), the error says which\nstatements stayed committed (`Oracle committed statements 1 to 2 of 4`). After a\nPL/SQL block or a `CALL` ran, toil can\'t see whether it committed, so the error says the statements\nup to the failure may have committed; check before running the script again. Only when\nnothing in the script could have committed does it say nothing was applied (an\nautonomous-transaction trigger or function is the exception; see the known limit above). Keep DDL in a\nscript of its own, or first.\n\n### Time limits and cancelling\n\nEvery command stops at `TOIL_TIMEOUT_MS` (default 120000) with `TIMEOUT`, and on\nCtrl+C or an MCP cancel with `CANCELLED`. The answer comes back straight away.\nSQLite can only be stopped between rows, though: a statement that computes for a long\ntime before producing its first row keeps running in the background until it\nfinishes, and the CLI process exits only then. Prefer `LIMIT` and indexed filters on\nlarge tables.\n\nPostgreSQL stops the statement on the server: on a time limit or a cancel, toil asks\nthe server to cancel it (`pg_cancel_backend`, from a second short connection), so a\nlong sort or `pg_sleep` doesn\'t keep running after toil has answered. `db query`\nreads rows a batch at a time from a server-side portal, so the server stops\nproducing rows once the page is full.\n\nMySQL stops the statement on the server too, with `KILL <id>` from a second short\nconnection. That ends the whole session, so a cancelled `db execute` rolls back and\nruns none of its remaining statements. Its protocol has no portal, so `db query` reads rows as they stream and,\nonce the page is full, drops the connection; the server stops at the next row it\ntries to send.\nSQL Server stops the statement on the server too: on a time limit or a cancel, toil\nsends a TDS attention, which ends the running batch, and the read\'s transaction is\nrolled back when its connection closes.\n\nOracle is sent a break (`connection.break()`) on a time limit or a cancel, which stops\nthe statement on the server at its next check: a long join or sort stops at once.\nThin mode\'s break travels in the data stream, so a session parked in\n`DBMS_SESSION.SLEEP` hears it only when the sleep ends; toil still answers straight\naway. `db query` reads rows a batch at a time from a server-side cursor.\n\n## Examples\n\n```bash\ntoil db table list\ntoil db table describe people\ntoil db table preview people --limit 20\ntoil db query "SELECT id, name FROM people WHERE active = 1 ORDER BY id" --limit 50\ntoil db query "SELECT id, name FROM people WHERE active = 1 ORDER BY id" --limit 50 --cursor <meta.page.nextCursor>\ntoil db execute "UPDATE people SET active = 0 WHERE id = 7" --allow-write --connection scratch\n```\n\nOver MCP:\n\n```json\n{ "name": "db_query", "arguments": { "sql": "SELECT id, name FROM people ORDER BY id", "limit": 50 } }\n```\n\n## Errors\n\n| Code | Means |\n|------|-------|\n| `NOT_CONFIGURED` | No db connection set up (`db lint` needs one only without `--engine`) |\n| `CONFIG_INVALID` | A connection is missing `engine` or a key its engine needs (`path`; `host`, `database`, `user`), `path` is relative, the file isn\'t a SQLite database, `"auth": "windows"` is set off Windows, or an Oracle `host` or `database` holds more than a host name or service name |\n| `AUTH` | The server refused the login: check `user` and `password` (for SQL Server, also that SQL Server logins are allowed; for Oracle, also a locked or expired account, or a password verifier too old for Thin mode); or Windows authentication couldn\'t start (Constrained Language mode, SSPI refused) |\n| `NETWORK` | The server or listener couldn\'t be reached, didn\'t answer, or its TLS certificate wasn\'t trusted; or SQL Server requires encryption and `ssl` is off |\n| `NOT_FOUND` | The file, database, Oracle service, schema or table doesn\'t exist |\n| `WRITE_DISABLED` | A write was refused: by `db query` (by the pre-flight lint before it ran, or by the engine; DDL included, on Oracle), or by the write gate on `db execute` |\n| `INVALID_INPUT` | Bad flags, a cursor from another query, SQL the pre-flight lint refused (another engine\'s syntax, an unclosed quote), several statements in `db query`, or on a read `VACUUM` (SQLite), `COPY` and `DO` (PostgreSQL), `INTO OUTFILE` and `SET` (MySQL), transaction control and `OUTPUT` (SQL Server), or PL/SQL (Oracle) |\n| `DATABASE` | The engine refused or failed the statement: bad SQL, a constraint, a lock, a permission; on SQL Server, also SQL that ended toil\'s transaction itself |\n| `TIMEOUT`, `CANCELLED` | Stopped waiting; for `db execute`, check whether the change was made before retrying |\n',
140329
- "dossiers.md": '---\ndescription: One body of work, its repositories, tracker, pipelines and environments, mapped to the connections that reach them. Why dossiers exist, where they live, one field by field, and how to create, check, use and share one\n---\n\n# What is a dossier?\n\nA **dossier** is one body of work, meaning its repositories, tracker, pipelines and\nenvironments, mapped to the connections that reach them. It\'s a small JSON file that\nsays "for `card-payments`, Jira is project `PAY` on `jira.imagile.dev`, the code is\n`payments-core` in Bitbucket, Jenkins builds the `payments-core` job, and dev runs in\nthe `payments-dev` namespace". It holds no secret, can\'t add a host and can\'t turn on\nwrites. It only chooses among connections you already have.\n\n<!-- figure: dossier-map -->\n\nIn words: the repository you work in matches the dossier `card-payments`. The dossier\nhas one section per area (Jira, Bitbucket, Jenkins, and OpenShift per environment),\nand each section picks one of your own connections by its host. The connection holds\nthe credential and is the only thing that talks to the host.\n\n## Why it exists\n\n- **One name instead of the same flags on every call.** Without a dossier, every\n command repeats where the work lives:\n `toil bitbucket pr list --connection corp-bitbucket --project PAY --repo payments-core`.\n With one, inside a clone of `payments-core` it\'s `toil bitbucket pr list`, and from\n anywhere else `toil bitbucket pr list --dossier card-payments`. A value you pass\n still wins over the dossier\'s.\n- **Scoping for agents.** An agent working in the repository gets the right project,\n repository and connection without being told, and every envelope says where each\n value came from (`meta.context`). The dossier can\'t widen what the agent may do: it\n holds no credential, can\'t point a connection at a new host, and a write on a\n connection it chose waits until you adopt it (**Writes**, below).\n- **What Toil UI shows.** Toil UI draws one dashboard per dossier: the stories, pull\n requests, builds and deployments of exactly the areas the dossier names.\n- **Knowledge that outlives the handover.** Repositories, project keys, field ids,\n boards and namespaces are written down once, in a file a team can review, instead\n of in one person\'s shell history.\n\n<!-- figure: dossier-cartoon -->\n\n## Areas, connections and dossiers\n\nThree words, three jobs:\n\n- **An area** is a kind of service toil speaks to: `jira`, `bitbucket`, `jenkins`,\n `openshift`. Each has its own commands and its own file in this skill.\n- **A connection** is one instance of an area, set up by a person in\n `~/.toil/config.json` or env vars: its host (`baseUrl`), its credential (in the OS\n credential store or an env var, never the file) and whether `writes` are on.\n `toil connections list` names yours. A dossier never holds any of this.\n- **A dossier** is one body of work: which connection each area uses for it, and the\n keys a call needs there (a project, a repository, a namespace per environment).\n Anyone, an agent included, may build one with `toil dossiers`.\n\nCredentials stay with connections; knowledge about the work goes in dossiers. That\nsplit is why a dossier may be checked into a repository when config may not.\n\n## How a call uses a dossier\n\n<!-- figure: dossier-resolution -->\n\nEvery area command runs the same steps, on the CLI and over MCP alike:\n\n1. **Pick the dossier.** `--dossier <name|file>` (or `TOIL_DOSSIER`) if given, else\n the one whose repository matches the folder you\'re in, by its path or its git\n remote. `--cwd <dir>` looks from another folder. No match means no dossier, and the\n command needs its inputs as flags, as it always would.\n2. **Pick the section.** The area\'s section, or `environments.<env>.<area>` for the\n environment: the call\'s `--env` when the area has one, else the dossier\'s `env`.\n3. **Fill the inputs.** Each context input the area declares (`--project`, `--repo`,\n `--owner`) resolves in one order: the call\'s own value, then the dossier, then the\n git remote, then the connection\'s setting, then the area\'s default.\n `toil <area> --help` says which inputs a dossier can fill ("defaults to your\n dossier\'s \u2026").\n4. **Pick the connection.** By the section\'s `connection` name, or by its `host`,\n which selects your connection whose `baseUrl` has that host. toil never sends\n anything to a host because a dossier named it; the host is only a selector.\n5. **Send the request** with that connection\'s credential, and report what was used\n in `meta.context`.\n\nA real envelope from `toil bitbucket pr list`, run in a clone of `payments-core`\n(the host doesn\'t resolve, which is the point of a placeholder):\n\n```json\n"meta": {\n "context": {\n "dossier": { "name": "card-payments", "source": "user", "by": "folder", "match": "remote", "repo": "payments-core" },\n "connection": { "value": "corp-bitbucket", "source": "dossier", "host": "bitbucket.imagile.dev" },\n "inputs": {\n "project": { "value": "PAY", "source": "dossier" },\n "repo": { "value": "payments-core", "source": "dossier" }\n }\n }\n}\n```\n\nThe request it sent was\n`GET https://bitbucket.imagile.dev/rest/api/1.0/projects/PAY/repos/payments-core/pull-requests`.\n\n## A dossier, field by field\n\n`~/.toil/dossiers/card-payments.json`, as `toil dossiers` writes it, with notes added:\n\n```jsonc\n{\n "name": "card-payments", // how you call it: --dossier card-payments\n "description": "Card payments v2: tokenised cards at the edge.",\n "env": "dev", // the default environment; a key of "environments"\n "repos": [ // how toil knows you\'re in this work\n { "name": "payments-core",\n "remotes": ["ssh://git@bitbucket.imagile.dev:7999/pay/payments-core.git"] }\n ],\n "jira": { // one section per area\n "host": "jira.imagile.dev", // selects your Jira connection on this host\n "project": "PAY", // a context input: fills --project\n "fields": { "storyPoints": "customfield_10002" }, // so --field storyPoints=5 works\n "transitions": { "Story": { "review": "Peer Review" } } // so --to review finds it\n },\n "bitbucket": { "host": "bitbucket.imagile.dev", "project": "PAY", "repo": "payments-core" },\n "jenkins": { "host": "jenkins.imagile.dev", "jobs": ["payments-core"] }, // "jobs": reference data\n "environments": {\n "dev": { "openshift": { "host": "api.ocp-nonprod.imagile.dev", "namespace": "payments-dev" } },\n "prod": { "openshift": { "host": "api.ocp.imagile.dev", "namespace": "payments-prod" } }\n },\n "people": [ // who is who in each system\n { "name": "Pat Example", "email": "you@example.com",\n "ids": { "jira": "pat", "github": "pat-ex", "ado": "you@example.com" } },\n { "name": "Claude", "kind": "agent", "ids": { "github": "claude" } }\n ],\n "wipLimit": 3 // items one person may have in progress at once\n}\n```\n\n- **`name`**: lowercase letters, digits and single hyphens, like a connection\'s name.\n- **`description`**: for people, and for the dossier list in Toil UI.\n- **`env`**: the environment calls use when they don\'t pass `--env`.\n- **`repos`**: each has a `name`, optional `remotes` and an optional local `path`. A\n folder matches by path first, then by its `origin` remote, so a fresh clone anywhere\n still resolves. Remotes are only compared, never contacted, and toil strips any\n credential from one before storing it.\n- **An area\'s section** (`jira`, `bitbucket`, \u2026) holds:\n - `host` or `connection`, never both. `host` suits a shared dossier, since\n teammates name their connections differently; `connection` names one of yours.\n With neither, the area\'s default connection is used.\n - the area\'s context inputs by name (`project`, `repo`, `owner`). A value may also\n be an object of repo name to value, for a dossier with several repositories.\n - `fields`: friendly names for custom field ids, used by `--field`.\n Toil UI also reads the Open Work Item keys there (`estimate`, `estimateUnit`,\n `priority`, `type`, `team`, `dueDate`, `iteration`) when it maps the area\'s work\n items, and for a GitHub repository with no board, `estimateLabel` (the label that\n holds an estimate, `{n}` for the number: `"estimateLabel": "size/{n}"`) and\n `iterationDays` (how many days each milestone runs as a sprint, as text like every\n value in `fields`: `"iterationDays": "14"`, not `14`). Without them a\n GitHub issue\'s milestone is its sprint and a `points: N` label its estimate.\n - `transitions`: per work item type, the transition or status each intent\n (`start`, `review`, `done`, `reopen`) means, used first by `--to` on `issue\n transition` and `work-item transition` (`core.md`, **Moving work items by\n intent**). Anything else under it fails `toil dossiers check`.\n - anything else (`jobs`, `boards`, `deployments`, an OpenShift `namespace`) is\n **reference data**: kept as written for people, agents, Toil UI and\n `check-dossier` to read, and never applied to a call. Adding one says so in\n `meta.warnings`.\n- **`environments`**: per environment, sections that replace the area\'s own section\n when that environment applies (`--env prod`, or the dossier\'s `env`).\n- **`people`**: the team, agents included, each with a `name`, an optional `kind`\n (`human`, the default, or `agent`), an optional `email`, and `ids`: the account each\n area knows them by, keyed by area. An identity is the user name, login or email that\n system shows (a Jira user name, a GitHub login, an Azure DevOps unique name or\n email, a Bitbucket Cloud account id); a `jira` or `ado` identity covers the Cloud\n variant too unless the dossier names it. It is never a credential: toil refuses a\n value shaped like a token, and one account can be only one person\'s. The `email` is\n only compared, so Toil UI can suggest which unmapped accounts are probably theirs;\n it never maps one by itself. Toil UI\'s People view reads this section, and an item\n assigned on the tracker to one of the dossier\'s agents is queued in Toil UI\'s Agent\n inbox, where it waits for a person to start it.\n- **`wipLimit`**: how many items one person may have in progress at once, as the team\n agreed. Toil UI counts each person\'s work in progress against it, and nothing else.\n\n## Where dossiers live\n\n<!-- figure: dossier-sources -->\n\ntoil reads dossiers on every area command from three kinds of place, and every\nlisting says which one each came from (`source`):\n\n1. **Your own**, `~/.toil/dossiers/<name>.json` (`user`). The commands that build a\n dossier write here.\n2. **Folders you list**, in `"dossierPaths"` in your config or `TOIL_DOSSIER_PATHS`\n (`listed`): a team repository of dossiers, cloned once. toil reads only folders you\n list and never searches for others.\n3. **The repository you\'re in**, `.toil/dossiers/*.json` at its root (`repo`). A\n service can carry its own dossier.\n\nA file passed by path (`--dossier ./card-payments.json`) is a fourth, `file`.\n\n**Same name in two places:** your own wins, then a listed folder, then the\nrepository, so you can override a teammate\'s copy without editing it.\n`toil dossiers list` shows the one left out under `shadowedBy`, and the call warns.\n**Two different dossiers that both match** the folder fail with `INVALID_INPUT` until\nyou pass `--dossier`. toil never guesses, and never picks the one you used last.\n\n## Create, check, use, share\n\n### Create\n\nOn the command line, or let an agent run the same commands:\n\n```bash\ntoil repos scan\ntoil dossiers init card-payments --description "Card payments v2"\ntoil dossiers add-repo card-payments ./payments-core\ntoil dossiers link card-payments jira --host jira.imagile.dev --set project=PAY\ntoil dossiers link card-payments bitbucket --host bitbucket.imagile.dev --set project=PAY --set repo=payments-core\ntoil dossiers env card-payments dev openshift --host api.ocp-nonprod.imagile.dev --default\ntoil dossiers field card-payments jira storyPoints customfield_10002\ntoil dossiers person card-payments "Pat Example" --id jira=pat --id github=pat-ex --email you@example.com\ntoil dossiers person card-payments Claude --kind agent --id github=claude\ntoil dossiers wip-limit card-payments 3\n```\n\n`toil dossiers person` adds a person, or more identities to one already there.\nRemoving a person or an identity (`--remove`) and clearing the limit\n(`toil dossiers wip-limit <dossier> --clear`) are deletes, so they run on the CLI only.\n\nEach command returns the change it made, refuses a value that\'s already there unless\n`--replace`, and needs no `--allow-write`, since it only writes your own dossier.\nThe same steps are under **Settings \u2192 Dossiers** in Toil UI, and, apart from people\nand the limit, under **Dossiers** in the menu a bare `toil` opens. Both run these\ncommands; neither edits the file itself.\n\n### Check\n\n`toil dossiers check card-payments` finds problems **without contacting any\nservice**: keys given twice, an unknown section, a `connection` you don\'t have, a\n`host` that matches none of your connections or more than one, a remote with a\ncredential in it. Each problem names its key path:\n\n```json\n{ "level": "error", "code": "DOSSIER_HOST_UNMATCHED", "path": "sonar.host",\n "message": "Dossier card-payments uses the sonar connection on sonar.imagile.dev, and you have no sonar connection with that host." }\n```\n\n`toil jira check-dossier --dossier card-payments` goes one step further and asks the\nservice whether each project and field id the dossier names exists. `jira`,\n`jira-cloud`, `confluence`, `sonar`, `ado`, `bitbucket`, `github`, `openshift` and\n`dynatrace` each have one.\n\n### Use\n\nWork in the repository and the dossier applies by itself, or pass\n`--dossier card-payments` from anywhere. Before a call, `toil dossiers context` says\nwhich dossier the folder resolves to and why, and `toil dossiers show card-payments`\nsays, per area, the connection a call would use, whether writes are on for it, the\nenvironment and the inputs it supplies.\n\n### Share\n\n`toil dossiers export card-payments --repo .` writes a copy into the repository\'s\n`.toil/dossiers/`, with host selectors and no local paths. Commit it yourself; toil\nnever commits. A teammate with a clone gets it with no setup beyond their own\nconnections, and `toil dossiers import .toil/dossiers/card-payments.json` copies it\ninto their own folder, listing any connection they still need under `toSetUp`.\n\n### Writes\n\nA write on a connection the dossier chose waits for you. A dossier in your own folder\nis yours, so its choices are too. A checked-in, listed or loose one isn\'t: a write\nthrough it fails with `WRITE_DISABLED` until you pass `--connection` yourself, or\nadopt the dossier with `toil dossiers import`. The same holds for where the write\nlands: a write whose owner, repo or project came from a dossier you haven\'t adopted\nfails with `WRITE_DISABLED`, even on your default connection, until you adopt it or\npass `--owner`, `--repo` or `--project` yourself. Reads, field aliases and transition\npins follow any dossier straight away. Writes still need `writes: true` on\nthe connection and `--allow-write` on the call, as everywhere. Over MCP, and in Toil\nUI, the dossier commands refuse to point a dossier at a connection with writes on; a\nperson makes that link on the command line.\n\n## One dossier, three views\n\n<!-- figure: dossier-views -->\n\nThe same file reaches each reader its own way: `toil dossiers show` on the command\nline; for an agent, the `dossiers_show` tool, the `toil://dossiers/<name>` resource and\n`meta.context` on every call it makes; and a dashboard per dossier in Toil UI.\n\n## FAQ\n\n- **Do I need a dossier?** No. Without one, commands take their inputs as flags or\n from the connection, exactly as before.\n- **Is it safe to commit one?** Yes, that\'s what it\'s for. It holds no secret and no\n `writes`, and can only choose among connections each reader already has.\n- **Does toil contact the hosts in it?** Never because a dossier named them. A host\n is compared with your connections\' hosts, nothing more.\n- **Several services, one product?** One dossier, several `repos`, and per-repo values\n where they differ (`"repo": { "payments-core": "payments-core", "ledger": "ledger-svc" }`).\n- **One service in several products?** Put a dossier in each, and pass `--dossier`\n when the folder matches both.\n- **Edits while `toil mcp` runs?** Dossiers are read on every call, so an edit applies\n from the next one.\n\n## Common mistakes\n\n- **A `host` with no connection behind it.** `dossiers check` reports\n `DOSSIER_HOST_UNMATCHED`; the call fails with `NOT_CONFIGURED` and names the\n command to add one. It never falls back to the default connection.\n- **Expecting reference data to fill a flag.** Only an area\'s context inputs fill\n flags. The warning when you add a key says which it is.\n- **Two dossiers for one folder.** The call fails until you pass `--dossier`. Merge\n them, or keep one in another repository.\n- **A write through a teammate\'s dossier.** `WRITE_DISABLED`, by design: adopt it with\n `toil dossiers import`, or pass `--connection` and the target flags (`--owner`,\n `--repo`, `--project`) yourself. Over MCP, ask the user to adopt it.\n- **A token in a remote.** toil strips userinfo before storing a remote, and\n `dossiers check` fails a hand-edited file that still has one\n (`DOSSIER_REMOTE_USERINFO`).\n- **Editing the JSON by hand and giving a key twice.** JSON parsers keep the last one\n quietly; toil reports `DOSSIER_DUPLICATE_KEY` with its path instead.\n',
140432
+ "dossiers.md": '---\ndescription: One body of work, its repositories, tracker, pipelines and environments, mapped to the connections that reach them. Why dossiers exist, where they live, one field by field, and how to create, check, use and share one\n---\n\n# What is a dossier?\n\nA **dossier** is one body of work, meaning its repositories, tracker, pipelines and\nenvironments, mapped to the connections that reach them. It\'s a small JSON file that\nsays "for `card-payments`, Jira is project `PAY` on `jira.imagile.dev`, the code is\n`payments-core` in Bitbucket, Jenkins builds the `payments-core` job, and dev runs in\nthe `payments-dev` namespace". It holds no secret, can\'t add a host and can\'t turn on\nwrites. It only chooses among connections you already have.\n\n<!-- figure: dossier-map -->\n\nIn words: the repository you work in matches the dossier `card-payments`. The dossier\nhas one section per area (Jira, Bitbucket, Jenkins, and OpenShift per environment),\nand each section picks one of your own connections by its host. The connection holds\nthe credential and is the only thing that talks to the host.\n\n## Why it exists\n\n- **One name instead of the same flags on every call.** Without a dossier, every\n command repeats where the work lives:\n `toil bitbucket pr list --connection corp-bitbucket --project PAY --repo payments-core`.\n With one, inside a clone of `payments-core` it\'s `toil bitbucket pr list`, and from\n anywhere else `toil bitbucket pr list --dossier card-payments`. A value you pass\n still wins over the dossier\'s.\n- **Scoping for agents.** An agent working in the repository gets the right project,\n repository and connection without being told, and every envelope says where each\n value came from (`meta.context`). The dossier can\'t widen what the agent may do: it\n holds no credential, can\'t point a connection at a new host, and a write on a\n connection it chose waits until you adopt it (**Writes**, below).\n- **What Toil UI shows.** Toil UI draws one dashboard per dossier: the stories, pull\n requests, builds and deployments of exactly the areas the dossier names.\n- **Knowledge that outlives the handover.** Repositories, project keys, field ids,\n boards and namespaces are written down once, in a file a team can review, instead\n of in one person\'s shell history.\n\n<!-- figure: dossier-cartoon -->\n\n## Areas, connections and dossiers\n\nThree words, three jobs:\n\n- **An area** is a kind of service toil speaks to: `jira`, `bitbucket`, `jenkins`,\n `openshift`. Each has its own commands and its own file in this skill.\n- **A connection** is one instance of an area, set up by a person in\n `~/.toil/config.json` or env vars: its host (`baseUrl`), its credential (in the OS\n credential store or an env var, never the file) and whether `writes` are on.\n `toil connections list` names yours. A dossier never holds any of this.\n- **A dossier** is one body of work: which connection each area uses for it, and the\n keys a call needs there (a project, a repository, a namespace per environment).\n Anyone, an agent included, may build one with `toil dossiers`.\n\nCredentials stay with connections; knowledge about the work goes in dossiers. That\nsplit is why a dossier may be checked into a repository when config may not.\n\n## How a call uses a dossier\n\n<!-- figure: dossier-resolution -->\n\nEvery area command runs the same steps, on the CLI and over MCP alike:\n\n1. **Pick the dossier.** `--dossier <name|file>` (or `TOIL_DOSSIER`) if given, else\n the one whose repository matches the folder you\'re in, by its path or its git\n remote. `--cwd <dir>` looks from another folder. No match means no dossier, and the\n command needs its inputs as flags, as it always would.\n2. **Pick the section.** The area\'s section, or `environments.<env>.<area>` for the\n environment: the call\'s `--env` when the area has one, else the dossier\'s `env`.\n3. **Fill the inputs.** Each context input the area declares (`--project`, `--repo`,\n `--owner`) resolves in one order: the call\'s own value, then the dossier, then the\n git remote, then the connection\'s setting, then the area\'s default.\n `toil <area> --help` says which inputs a dossier can fill ("defaults to your\n dossier\'s \u2026").\n4. **Pick the connection.** By the section\'s `connection` name, or by its `host`,\n which selects your connection whose `baseUrl` has that host. toil never sends\n anything to a host because a dossier named it; the host is only a selector.\n5. **Send the request** with that connection\'s credential, and report what was used\n in `meta.context`.\n\nA real envelope from `toil bitbucket pr list`, run in a clone of `payments-core`\n(the host doesn\'t resolve, which is the point of a placeholder):\n\n```json\n"meta": {\n "context": {\n "dossier": { "name": "card-payments", "source": "user", "by": "folder", "match": "remote", "repo": "payments-core" },\n "connection": { "value": "corp-bitbucket", "source": "dossier", "host": "bitbucket.imagile.dev" },\n "inputs": {\n "project": { "value": "PAY", "source": "dossier" },\n "repo": { "value": "payments-core", "source": "dossier" }\n }\n }\n}\n```\n\nThe request it sent was\n`GET https://bitbucket.imagile.dev/rest/api/1.0/projects/PAY/repos/payments-core/pull-requests`.\n\n## A dossier, field by field\n\n`~/.toil/dossiers/card-payments.json`, as `toil dossiers` writes it, with notes added:\n\n```jsonc\n{\n "name": "card-payments", // how you call it: --dossier card-payments\n "description": "Card payments v2: tokenised cards at the edge.",\n "env": "dev", // the default environment; a key of "environments"\n "repos": [ // how toil knows you\'re in this work\n { "name": "payments-core",\n "remotes": ["ssh://git@bitbucket.imagile.dev:7999/pay/payments-core.git"] }\n ],\n "jira": { // one section per area\n "host": "jira.imagile.dev", // selects your Jira connection on this host\n "project": "PAY", // a context input: fills --project\n "fields": { "storyPoints": "customfield_10002" }, // so --field storyPoints=5 works\n "transitions": { "Story": { "review": "Peer Review" } } // so --to review finds it\n },\n "bitbucket": { "host": "bitbucket.imagile.dev", "project": "PAY", "repo": "payments-core" },\n "jenkins": { "host": "jenkins.imagile.dev", "jobs": ["payments-core"] }, // "jobs": reference data\n "environments": {\n "dev": { "openshift": { "host": "api.ocp-nonprod.imagile.dev", "namespace": "payments-dev" } },\n "prod": { "openshift": { "host": "api.ocp.imagile.dev", "namespace": "payments-prod" } }\n },\n "people": [ // who is who in each system\n { "name": "Pat Example", "email": "you@example.com",\n "ids": { "jira": "pat", "github": "pat-ex", "ado": "you@example.com" } },\n { "name": "Claude", "kind": "agent", "ids": { "github": "claude" } }\n ],\n "wipLimit": 3 // items one person may have in progress at once\n}\n```\n\n- **`name`**: lowercase letters, digits and single hyphens, like a connection\'s name.\n- **`description`**: for people, and for the dossier list in Toil UI.\n- **`env`**: the environment calls use when they don\'t pass `--env`.\n- **`repos`**: each has a `name`, optional `remotes` and an optional local `path`. A\n folder matches by path first, then by its `origin` remote, so a fresh clone anywhere\n still resolves. Remotes are only compared, never contacted, and toil strips any\n credential from one before storing it.\n- **An area\'s section** (`jira`, `bitbucket`, \u2026) holds:\n - `host` or `connection`, never both. `host` suits a shared dossier, since\n teammates name their connections differently; `connection` names one of yours.\n With neither, the area\'s default connection is used.\n - the area\'s context inputs by name (`project`, `repo`, `owner`). A value may also\n be an object of repo name to value, for a dossier with several repositories.\n - `fields`: friendly names for custom field ids, used by `--field`.\n Toil UI also reads the Open Work Item keys there (`estimate`, `estimateUnit`,\n `priority`, `type`, `team`, `dueDate`, `iteration`) when it maps the area\'s work\n items, and for a GitHub repository with no board, `estimateLabel` (the label that\n holds an estimate, `{n}` for the number: `"estimateLabel": "size/{n}"`) and\n `iterationDays` (how many days each milestone runs as a sprint, as text like every\n value in `fields`: `"iterationDays": "14"`, not `14`). Without them a\n GitHub issue\'s milestone is its sprint and a `points: N` label its estimate.\n - `transitions`: per work item type, the transition or status each intent\n (`start`, `review`, `done`, `reopen`) means, used first by `--to` on `issue\n transition` and `work-item transition` (`core.md`, **Moving work items by\n intent**). Anything else under it fails `toil dossiers check`.\n - anything else (`jobs`, `boards`, `deployments`, an OpenShift `namespace`) is\n **reference data**: kept as written for people, agents, Toil UI and\n `check-dossier` to read, and never applied to a call. Adding one says so in\n `meta.warnings`.\n- **`environments`**: per environment, sections that replace the area\'s own section\n when that environment applies (`--env prod`, or the dossier\'s `env`).\n- **`people`**: the team, agents included, each with a `name`, an optional `kind`\n (`human`, the default, or `agent`), an optional `email`, and `ids`: the account each\n area knows them by, keyed by area. An identity is the user name, login or email that\n system shows (a Jira user name, a GitHub login, an Azure DevOps unique name or\n email, a Bitbucket Cloud account id); a `jira` or `ado` identity covers the Cloud\n variant too unless the dossier names it. It is never a credential: toil refuses a\n value shaped like a token, and one account can be only one person\'s. The `email` is\n only compared, so Toil UI can suggest which unmapped accounts are probably theirs;\n it never maps one by itself. Toil UI\'s People view reads this section, and an item\n assigned on the tracker to one of the dossier\'s agents is queued in Toil UI\'s Agent\n inbox, where it waits for a person to start it.\n- **`wipLimit`**: how many items one person may have in progress at once, as the team\n agreed. Toil UI counts each person\'s work in progress against it, and nothing else.\n\n## Where dossiers live\n\n<!-- figure: dossier-sources -->\n\ntoil reads dossiers on every area command from three kinds of place, and every\nlisting says which one each came from (`source`):\n\n1. **Your own**, `~/.toil/dossiers/<name>.json` (`user`). The commands that build a\n dossier write here.\n2. **Folders you list**, in `"dossierPaths"` in your config or `TOIL_DOSSIER_PATHS`\n (`listed`): a team repository of dossiers, cloned once. toil reads only folders you\n list and never searches for others.\n3. **The repository you\'re in**, `.toil/dossiers/*.json` at its root (`repo`). A\n service can carry its own dossier.\n\nA file passed by path (`--dossier ./card-payments.json`) is a fourth, `file`.\n\n**Same name in two places:** your own wins, then a listed folder, then the\nrepository, so you can override a teammate\'s copy without editing it.\n`toil dossiers list` shows the one left out under `shadowedBy`, and the call warns.\n**Two different dossiers that both match** the folder fail with `INVALID_INPUT` until\nyou pass `--dossier`. toil never guesses, and never picks the one you used last.\n\n## Create, check, use, share\n\n### Create\n\nOn the command line, or let an agent run the same commands:\n\n```bash\ntoil repos scan\ntoil dossiers init card-payments --description "Card payments v2"\ntoil dossiers add-repo card-payments ./payments-core\ntoil dossiers link card-payments jira --host jira.imagile.dev --set project=PAY\ntoil dossiers link card-payments bitbucket --host bitbucket.imagile.dev --set project=PAY --set repo=payments-core\ntoil dossiers env card-payments dev openshift --host api.ocp-nonprod.imagile.dev --default\ntoil dossiers field card-payments jira storyPoints customfield_10002\ntoil dossiers person card-payments "Pat Example" --id jira=pat --id github=pat-ex --email you@example.com\ntoil dossiers person card-payments Claude --kind agent --id github=claude\ntoil dossiers wip-limit card-payments 3\ntoil dossiers describe card-payments --name payments-v2 --description "Card payments v2"\n```\n\n`toil dossiers person` adds a person, or more identities to one already there.\nRemoving a person or an identity (`--remove`) and clearing the limit\n(`toil dossiers wip-limit <dossier> --clear`) are deletes, so they run on the CLI only.\n`toil dossiers describe <dossier> [--name <new name>] [--description <text>]`\nrenames one of your own dossiers, moving its file with everything in it, or replaces\nits one-line description. A name you already use is refused, and so is a checked-in\nor listed dossier: import it first, then describe your copy.\n\nEach command returns the change it made, refuses a value that\'s already there unless\n`--replace`, and needs no `--allow-write`, since it only writes your own dossier.\nThe same steps are under **Settings \u2192 Dossiers** in Toil UI, where a dossier\'s name\nand description are also edited in place on its card and dashboard, and, apart from\npeople, the limit and `describe`, under **Dossiers** in the menu a bare `toil` opens.\nBoth run these commands; neither edits the file itself.\n\n### Check\n\n`toil dossiers check card-payments` finds problems **without contacting any\nservice**: keys given twice, an unknown section, a `connection` you don\'t have, a\n`host` that matches none of your connections or more than one, a remote with a\ncredential in it. Each problem names its key path:\n\n```json\n{ "level": "error", "code": "DOSSIER_HOST_UNMATCHED", "path": "sonar.host",\n "message": "Dossier card-payments uses the sonar connection on sonar.imagile.dev, and you have no sonar connection with that host." }\n```\n\n`toil jira check-dossier --dossier card-payments` goes one step further and asks the\nservice whether each project and field id the dossier names exists. `jira`,\n`jira-cloud`, `confluence`, `sonar`, `ado`, `bitbucket`, `github`, `openshift` and\n`dynatrace` each have one.\n\n### Use\n\nWork in the repository and the dossier applies by itself, or pass\n`--dossier card-payments` from anywhere. Before a call, `toil dossiers context` says\nwhich dossier the folder resolves to and why, and `toil dossiers show card-payments`\nsays, per area, the connection a call would use, whether writes are on for it, the\nenvironment and the inputs it supplies.\n\n### Share\n\nA dossier a team shares selects each area\'s connection by `host`, because teammates\nname their connections differently. toil makes that the default:\n\n- `toil dossiers init card-payments --shared` creates it in the repository\'s\n `.toil/dossiers/` (`--repo <root>` for another working tree).\n- `toil dossiers link` or `env` with `--connection` on a checked-in or listed dossier\n records that connection\'s host instead. On a terminal it asks first, and you may\n keep the name; anywhere else it records the host and warns `DOSSIER_HOST_RECORDED`.\n- `toil dossiers check` warns `DOSSIER_CONNECTION_SHARED` for a checked-in dossier\n that names a connection, and shows the `host` to use instead.\n\n`toil dossiers export card-payments --repo .` writes a copy of one of your own into\nthe repository\'s `.toil/dossiers/`, with host selectors and no local paths. Commit it\nyourself; toil never commits. A teammate with a clone gets it with no setup beyond\ntheir own connections: `toil dossiers onboard` (below) sets those up. `toil dossiers\nimport .toil/dossiers/card-payments.json` copies it into their own folder instead,\nlisting any connection they still need under `toSetUp`.\n\n### Writes\n\nA write on a connection the dossier chose waits for you. A dossier in your own folder\nis yours, so its choices are too. A checked-in, listed or loose one isn\'t: a write\nthrough it fails with `WRITE_DISABLED` until you pass `--connection` yourself, or\nadopt the dossier with `toil dossiers import`. The same holds for where the write\nlands: a write whose owner, repo or project came from a dossier you haven\'t adopted\nfails with `WRITE_DISABLED`, even on your default connection, until you adopt it or\npass `--owner`, `--repo` or `--project` yourself. Reads, field aliases and transition\npins follow any dossier straight away. Writes still need `writes: true` on\nthe connection and `--allow-write` on the call, as everywhere. Over MCP, and in Toil\nUI, the dossier commands refuse to point a dossier at a connection with writes on; a\nperson makes that link on the command line.\n\n## Onboarding to a repo that has a dossier\n\n<!-- figure: dossier-onboard -->\n\nClone a repository with a dossier in `.toil/dossiers/`, then run one command in it:\n\n```bash\ntoil dossiers onboard\n```\n\nFor each area the dossier covers, it looks for your connection the way a call would:\n\n- **One matches** the section\'s `host` (or its `connection` name, or your default):\n it says so, and uses it.\n- **None matches:** it offers to add one through `toil connections add`, with a base\n URL on that host already offered (`https://api.github.com` for `github.com`) and the\n token typed hidden, straight into your OS credential store. A base URL on another\n host is refused before anything is saved.\n- **Several match:** it asks which one, and pins it in your own copy,\n `~/.toil/dossiers/<name>.json`. That copy then applies wherever the checked-in one\n does, and since it is yours, writes may follow it.\n\nIt ends with `toil dossiers check` and one test read per connection (the same read\n`toil connections test` sends), and the CLI exits 1 unless every area resolved and\nread. `--pin <area>=<connection>` answers the several-match question without asking,\nfor every section of the area; `--pin environments.prod.github=<connection>` pins one\nsection apart from the rest.\nWith no terminal, or with `--plan`, it asks nothing and adds no connection: each area\nsays what it needs and the command that sets it up (a `--pin` still applies).\n\nIt asks for tokens, so it is CLI only, and Toil UI runs it as a person\'s command\n(**Settings \u2192 Dossiers**, Set up this repo); it is never an MCP tool. The menu a bare\n`toil` opens has it under **Dossiers** too.\n\n## One dossier, three views\n\n<!-- figure: dossier-views -->\n\nThe same file reaches each reader its own way: `toil dossiers show` on the command\nline; for an agent, the `dossiers_show` tool, the `toil://dossiers/<name>` resource and\n`meta.context` on every call it makes; and a dashboard per dossier in Toil UI.\n\n## FAQ\n\n- **Do I need a dossier?** No. Without one, commands take their inputs as flags or\n from the connection, exactly as before.\n- **Is it safe to commit one?** Yes, that\'s what it\'s for. It holds no secret and no\n `writes`, and can only choose among connections each reader already has.\n- **Does toil contact the hosts in it?** Never because a dossier named them. A host\n is compared with your connections\' hosts, nothing more.\n- **Several services, one product?** One dossier, several `repos`, and per-repo values\n where they differ (`"repo": { "payments-core": "payments-core", "ledger": "ledger-svc" }`).\n- **One service in several products?** Put a dossier in each, and pass `--dossier`\n when the folder matches both.\n- **Edits while `toil mcp` runs?** Dossiers are read on every call, so an edit applies\n from the next one.\n\n## Common mistakes\n\n- **A `host` with no connection behind it.** `dossiers check` reports\n `DOSSIER_HOST_UNMATCHED`; the call fails with `NOT_CONFIGURED` and names the\n command to add one. It never falls back to the default connection.\n- **Expecting reference data to fill a flag.** Only an area\'s context inputs fill\n flags. The warning when you add a key says which it is.\n- **Two dossiers for one folder.** The call fails until you pass `--dossier`. Merge\n them, or keep one in another repository.\n- **A write through a teammate\'s dossier.** `WRITE_DISABLED`, by design: adopt it with\n `toil dossiers import`, or pass `--connection` and the target flags (`--owner`,\n `--repo`, `--project`) yourself. Over MCP, ask the user to adopt it.\n- **A token in a remote.** toil strips userinfo before storing a remote, and\n `dossiers check` fails a hand-edited file that still has one\n (`DOSSIER_REMOTE_USERINFO`).\n- **Editing the JSON by hand and giving a key twice.** JSON parsers keep the last one\n quietly; toil reports `DOSSIER_DUPLICATE_KEY` with its path instead.\n',
140330
140433
  "dynatrace.md": '---\narea: dynatrace\ndescription: Monitored entities, services, Kubernetes workloads, problems and distributed traces from Dynatrace\n---\n\n# Dynatrace (`dynatrace`)\n\nMonitored entities, services, Kubernetes workloads and problems from the Dynatrace\n**Environment API v2**, and distributed-trace spans from **Grail**. Every command\nreads; none changes anything. Verification level: `unit`.\n\n**Supported versions:** The oldest Dynatrace version toil supports hasn\'t been established. The\nclassic commands call Environment API v2 (`/api/v2`) on SaaS and Managed; `trace get`\nneeds the platform Grail query API (`/platform/storage/query/v1`), so a deployment\nwithout the platform can\'t run it. No release has been verified yet.\n\n## Credential\n\nTwo hosts, two tokens, and each token goes only to its own host:\n\n- **Access token**, for every command except `trace get`. In Dynatrace: Access tokens \u2192\n Generate new token, with the `entities.read` and `problems.read` scopes. toil sends\n it to `baseUrl` as `Authorization: Api-Token <token>`.\n- **Platform token**, for `trace get` only, with the `storage:spans:read` and\n `storage:buckets:read` scopes. toil sends it to `platformUrl` as\n `Authorization: Bearer <token>`.\n\nThere is no username, password or browser login, and no CI fallback variable.\n\n## Configuration\n\n| Key | Env var | Required | Meaning |\n|-----|---------|----------|---------|\n| `baseUrl` | `TOIL_DYNATRACE_BASE_URL` | for all but `trace get` | Classic environment URL, like `https://<environment-id>.live.dynatrace.com`. On Managed, keep the `/e/<environment-id>` path |\n| `apiToken` | `TOIL_DYNATRACE_API_TOKEN` | for all but `trace get` | Access token, sent as `Api-Token` |\n| `platformUrl` | `TOIL_DYNATRACE_PLATFORM_URL` | for `trace get` | Platform URL, like `https://<environment-id>.apps.dynatrace.com` |\n| `platformToken` | `TOIL_DYNATRACE_PLATFORM_TOKEN` | for `trace get` | Platform token, sent as `Bearer` |\n| `env` | `TOIL_DYNATRACE_ENV` | no | The environment name `--env` selects this connection by, when it differs from the connection\'s name |\n\nA command that needs a missing key fails with `NOT_CONFIGURED` naming it\n("Dynatrace baseUrl not configured.").\n\nEnvironment variables (CI, or a one-off shell):\n\n```bash\nexport TOIL_DYNATRACE_BASE_URL=https://dynatrace.imagile.dev\nexport TOIL_DYNATRACE_API_TOKEN=<your access token>\nexport TOIL_DYNATRACE_PLATFORM_URL=https://dynatrace-platform.imagile.dev\nexport TOIL_DYNATRACE_PLATFORM_TOKEN=<your platform token>\n```\n\n## Environments\n\nEach Dynatrace environment is one connection. `--env <name>` picks the connection\nnamed `<name>`, or the one whose `env` setting is `<name>`; an environment toil\ndoesn\'t know is an `INVALID_INPUT` that lists the ones it has. Without `--env`, the\narea\'s default connection is used: the one named in `defaults.dynatrace.connection`,\nelse the one named `dynatrace`, else the only one. Keys every environment shares\n(often `platformUrl`) can go once under `defaults.dynatrace`; a connection\'s own\nvalue wins over them.\n\n```json\n{\n "version": 2,\n "connections": {\n "prod": { "area": "dynatrace", "baseUrl": "https://dynatrace.imagile.dev" },\n "staging": { "area": "dynatrace", "baseUrl": "https://dynatrace.imagile.dev/e/abc12345-0000-0000-0000-000000000000" }\n },\n "defaults": { "dynatrace": { "connection": "prod" } }\n}\n```\n\nThe tokens never go in this file; a plaintext one there is refused with\n`CONFIG_INVALID`. Run `toil connections add prod --area dynatrace` (or\n`toil connections login prod` for an existing connection) to keep them in the OS\ncredential store, or set the env vars. `TOIL_DYNATRACE_*` variables configure the\ndefault connection only; for another one use `TOIL_CONN_<NAME>_<KEY>`\n(`TOIL_CONN_STAGING_API_TOKEN`).\n\n```bash\ntoil dynatrace --env staging problem list\n```\n\n## Commands\n\n- `entity list`: List monitored entities using an entity selector. `--selector`\n is required; `--from`, `--to` and `--fields` are passed through.\n- `entity get <id>`: Get a monitored entity by ID (`--from`, `--to`, `--fields`). `data` is Dynatrace\'s entity as it came.\n- `service list`: List monitored services: `entity list` with `type("SERVICE")`\n (`--from`, `--to`). `data` is `{ totalCount, services }`.\n- `workload list`: List monitored Kubernetes workloads: `entity list` with\n `type("CLOUD_APPLICATION")` (`--from`, `--to`). `data` is `{ totalCount, workloads }`.\n- `problem list`: List problems. `--from` defaults to `now-2h` and `--to` to `now`;\n `--problem-selector` and `--entity-selector` filter. `data` is\n `{ totalCount, problems }`.\n- `problem get <id>`: Get a problem by ID (`--fields`). `data` is Dynatrace\'s\n problem as it came. A problem id often starts with `-`; on the CLI, put `--`\n before it so it isn\'t read as a flag (`problem get -- -1234567890123456789_1700000000000V2`).\n- `trace get <id>`: Get distributed-trace spans from Grail (the id is 16 to 32\n hexadecimal characters). It runs `fetch spans | filter trace.id == "<id>" | sort start_time asc`\n and waits up to 60 seconds for Grail, polling at most once a second; past that it\n fails with `TIMEOUT`. `data` is the query\'s `result` (`records`, `types`,\n `metadata`). The query sends no timeframe and no record limit, so Grail\'s\n defaults apply: an old trace or a very large one may come back empty or cut short.\n\nThe lists fetch every page, 500 at a time, until Dynatrace stops returning a\n`nextPageKey`; `totalCount` is the number of items collected. They stop with an\nerror after 1,000 pages, and like every command they\'re subject to toil\'s time limit\n(`TOIL_TIMEOUT_MS`, 120 s by default).\n\nDynatrace\'s own error text isn\'t shown yet: an error is the status line, such as\n`HTTP 400 Bad Request`, with toil\'s fix.\n\n```bash\ntoil dynatrace entity list --selector \'type("HOST"),tag("team:payments")\'\ntoil dynatrace problem list --from now-1d --problem-selector \'status("open")\'\ntoil dynatrace trace get 4bf92f3577b34da6a3ce929d0e0e4736\n```\n\n## Checking a dossier\n\n`check-dossier` checks the call\'s dossier for the call\'s environment (`--env`, else the dossier\'s own): each entity id it names (`entity`, `entities`) exists, through `/api/v2/entities/{id}`. It\'s `toil dynatrace check-dossier` (`--dossier <name|file>`, or the dossier the folder resolves to), and it returns `{ dossier, connection, env, ok, checked, checks, unchecked }`, one check per value with its key path. The CLI exits 1 when one is missing. A failure other than not-found (a bad token, an unreachable host) fails the command. Read only.\n',
140331
140434
  "elasticsearch.md": '---\narea: elasticsearch\ndescription: Cluster health, the index list, and search and count with Query DSL or a Lucene query string on Elasticsearch\n---\n\n# Elasticsearch (`elasticsearch`)\n\nCluster health, the index list, and document search and count on **Elasticsearch**,\nthrough its REST API. Every command reads; none changes anything. Verification\nlevel: `unit`.\n\n**Supported versions:** The oldest Elasticsearch version toil supports hasn\'t been established. toil\ncalls `_cluster/health`, `_cat/indices`, `_search` and `_count` with an API key sent as\nan `ApiKey` header, following Elastic\'s current REST API reference. No release has\nbeen verified yet.\n\n## Credential\n\nAn Elasticsearch **API key**: in Kibana, Stack Management \u2192 API keys \u2192 Create API key\n(or Elasticsearch\'s own `POST /_security/api_key`). Copy the **encoded** value, the\nbase64 string shown once when the key is created. Give it the `read` index privilege\non the indices you\'ll search and count, `monitor` on those you\'ll list, and the\n`monitor` cluster privilege for `cluster health` and `index list`. toil sends it as\n`Authorization: ApiKey <encoded>`. There is no username, password or browser login.\n\n## Configuration\n\n| Key | Env var | Required | Meaning |\n|-----|---------|----------|---------|\n| `baseUrl` | `TOIL_ELASTICSEARCH_BASE_URL` | yes | Elasticsearch root, e.g. `https://elasticsearch.imagile.dev` (keep any context path). Elasticsearch itself, not Kibana |\n| `apiKey` | `TOIL_ELASTICSEARCH_API_KEY` | yes | The encoded API key |\n\nThere\'s no CI fallback variable.\n\nEnvironment variables (CI, or a one-off shell):\n\n```bash\nexport TOIL_ELASTICSEARCH_BASE_URL=https://elasticsearch.imagile.dev\nexport TOIL_ELASTICSEARCH_API_KEY=<your encoded API key>\n```\n\nOr `~/.toil/config.json`:\n\n```json\n{\n "version": 2,\n "connections": {\n "es-prod": { "area": "elasticsearch", "baseUrl": "https://elasticsearch.imagile.dev" }\n },\n "defaults": { "elasticsearch": { "connection": "es-prod" } }\n}\n```\n\nThe key never goes in this file; a plaintext one there is refused with\n`CONFIG_INVALID`. Run `toil connections add es-prod --area elasticsearch` (or\n`toil connections login es-prod` for an existing connection) to keep it in the OS\ncredential store, or set `TOIL_ELASTICSEARCH_API_KEY`.\n\n**Sharing the key with Kibana:** a Kibana connection can use this connection\'s key\ninstead of its own, but only when you pair them on the Kibana side\n(`"apiKeyFrom": "es-prod"`). An unpaired Kibana connection never gets it. The one\nexception is an env fallback the contract specifies: Kibana\'s default connection takes\n`TOIL_ELASTICSEARCH_API_KEY` when `TOIL_KIBANA_API_KEY` isn\'t set. Either way the key\nis sent only to that Kibana connection\'s own host. See `kibana.md`.\n\n## Commands\n\n- `cluster health`: Show cluster health (status, node and shard counts), as\n Elasticsearch reports it. A red cluster is a successful answer whose `status` is\n `red`.\n- `index list`: List indices with health, document count and size (`--pattern`\n takes a name or wildcard, comma-separate several). `data` is `{ count, indices }`,\n each row the `_cat/indices` columns `index`, `health`, `status`, `docs.count`,\n `store.size`, `pri` and `rep`, every value a string.\n- `index search <index>`: Search one or more indices with Query DSL JSON or a query\n string. The index is required (comma-separate several; wildcards and aliases work; an empty\n name or an empty entry between commas is refused, so nothing silently searches every\n index).\n `--query` takes one Query DSL clause as a JSON object, `--q` a Lucene query string;\n use one or the other, and with neither every document matches. `--sort` takes\n `field:order` pairs, comma-separated (`@timestamp:desc,_score:desc`; an entry with\n no `asc` or `desc` sorts ascending). `--source` is a comma list of fields to return.\n `--limit` (default 100) and `--offset` (default 0) go to the server as its `size`\n and `from`; past 10,000 hits Elasticsearch refuses `from + size` (its\n `max_result_window`).\n `--timeout-ms` (default 30000) is how long toil waits for the answer. `index search`\n has a 10-minute time limit of its own, so a `--timeout-ms` up to 600000 is honoured;\n `TOIL_TIMEOUT_MS`, when set, overrides that limit. `data` is `{ index,\n took, timedOut, total, totalRelation, hitCount, hits, aggregations }`: `hits` as\n Elasticsearch sent them, and `totalRelation` `gte` when `total` is only a lower\n bound.\n- `index count <index>`: Count documents matching a query (`--query` or `--q` as\n for `index search`). `data` is `{ index, count }`.\n\n`index search` and `index count` send their query as a POST body. They still only read.\n\nErrors carry Elasticsearch\'s own reason, e.g. `index_not_found_exception: no such\nindex [nope]`, or a query parse error under its root cause, so a bad query can be\nfixed from the message.\n\n```bash\ntoil elasticsearch cluster health\ntoil elasticsearch index list --pattern "logs-*"\ntoil elasticsearch index search logs-app --q "level:error AND service:api" --sort "@timestamp:desc" --limit 20\ntoil elasticsearch index count "logs-*" --query \'{"term":{"level":"error"}}\'\n```\n',
140332
140435
  "figma.md": '---\narea: figma\ndescription: Figma files and nodes from a link, comments, version history and project files\n---\n\n# Figma (`figma`)\n\nFiles and single nodes (from a key or a pasted Figma link), comments, version\nhistory and project file lists, through the **Figma REST API** (`/v1/...`). Every\ncommand reads; none changes anything. Verification level: `unit`.\n\n**Supported versions:** The oldest Figma version toil supports hasn\'t been established. toil\ncalls the Figma REST API v1 with a personal access token in `X-Figma-Token`. Nothing\nhas been run against a live account yet.\n\n## Credential\n\nA Figma **personal access token**: in Figma, Settings \u2192 Security \u2192 Personal access\ntokens. toil sends it as the `X-Figma-Token` header, to the configured `baseUrl` and\nnowhere else. A redirect to another host is refused rather than followed, so the\ntoken never travels with it. There is no OAuth app, password or browser login.\n\n## Configuration\n\n| Key | Env var | Required | Meaning |\n|-----|---------|----------|---------|\n| `baseUrl` | `TOIL_FIGMA_BASE_URL` | yes | Figma API root: `https://api.figma.com` (toil has no built-in default) |\n| `token` | `TOIL_FIGMA_TOKEN` | yes | Personal access token |\n\nThere\'s no CI fallback variable.\n\nEnvironment variables (CI, or a one-off shell):\n\n```bash\nexport TOIL_FIGMA_BASE_URL=https://api.figma.com\nexport TOIL_FIGMA_TOKEN=<your personal access token>\n```\n\nOr `~/.toil/config.json`:\n\n```json\n{\n "version": 2,\n "connections": {\n "figma": { "area": "figma", "baseUrl": "https://api.figma.com" }\n },\n "defaults": { "figma": { "connection": "figma" } }\n}\n```\n\nThe token never goes in this file; a plaintext one there is refused with\n`CONFIG_INVALID`. Run `toil connections add figma --area figma` (or\n`toil connections login figma` for an existing connection) to keep it in the OS\ncredential store, or set `TOIL_FIGMA_TOKEN`.\n\n## Links, keys and node IDs\n\nWherever a command takes `<file-key-or-url>`, pass the file key or a link. A link\n(anything starting `http://` or `https://`) must contain `figma.com/design/<key>` or\n`figma.com/file/<key>`; anything else fails with "Could not extract Figma file key\nfrom URL". A value that isn\'t a link is used as the key as it stands. The link is\nparsed locally and never opened.\n\n- A branch link (`/design/<key>/branch/<branch-key>/...`) resolves to the main\n file\'s key, not the branch\'s.\n- FigJam (`/board/`), prototype (`/proto/`) and Slides (`/slides/`) links are\n refused; pass the bare key instead.\n- A node ID is `12:34` or `12-34` (dashes become colons), or for a layer inside an\n instance `I12:34;56:78`. `file get` takes it from `--node-id`, else from the link\'s\n `node-id` query parameter. A malformed one fails with "Invalid Figma node ID".\n\n## Commands\n\n- `file get <file-key-or-url>`: Get a Figma file \u2014 metadata, structure, and component/style inventory (or a\n single node with `--node-id`).\n - Whole file: `data` is `fileKey`, `name`, `lastModified`, `version`,\n `thumbnailUrl`, `role`, `editorType`, `schemaVersion`, `componentCount` and\n `styleCount`. The request sends `depth=1`, so component and style counts may be\n lower than with `--document`. `--document` drops `depth` and adds the full\n `document` tree, which can be large.\n - One node (`--node-id`, or a link with `node-id`): `GET /v1/files/<key>/nodes`;\n `data` is `fileKey`, `nodeId`, `name`, `lastModified`, `thumbnailUrl`, the node\'s\n whole `document` subtree (with or without `--document`), `componentCount` and\n `styleCount`. A node the answer doesn\'t hold is `NOT_FOUND` ("Node 12:34 not\n found in file ...").\n- `file comments <file-key-or-url>`: Get comments on a Figma file. `data` is `fileKey`, `count` and\n `comments` as Figma returns them. `--as-of <date>` is sent as `as_of`, a parameter\n Figma doesn\'t document, so every comment comes back regardless, and\n `meta.warnings` says so (`FIGMA_AS_OF_IGNORED`).\n- `file versions <file-key-or-url>`: Get the version history of a Figma file. `data` is `fileKey`, `count`\n and `versions`. Only the first page Figma returns is read; when Figma has more,\n `meta.warnings` says so (`FIGMA_MORE_VERSIONS`) and older versions are missing.\n- `project files <project-id>`: List files in a Figma project. `data` is `projectId`, `count` and\n `files`. The project ID is in the project\'s URL.\n- `whoami`: Get the current Figma user (useful for verifying credentials). `data` is\n Figma\'s answer as it came.\n\nImage links in the answers (`thumbnailUrl`, `thumbnail_url`, `img_url`) are returned\nas they are and never fetched; they\'re on Figma\'s image host, not the API.\n\n```bash\ntoil figma file get "https://www.figma.com/design/abc12345/Checkout?node-id=12-34"\ntoil figma file get abc12345 --document\ntoil figma file comments abc12345\ntoil figma whoami\n```\n',
140333
140436
  "git.md": "---\narea: git\ndescription: Local git status, diff, log, branches and a commit report for the repository in the workspace\n---\n\n# Local git (`git`)\n\nStatus, diff, recent commits, branches and a commits-and-lines report for the git\nrepository the workspace is in. Every command reads; none changes anything.\nVerification level: `unit`.\n\n**Supported versions:** The oldest git version toil supports hasn't been established. toil\nruns the git already on PATH and needs git 2.24 or later for its argument\nsafeguards; an older one gets `GIT_NOT_FOUND`. Output parsing was checked against\ngit 2.49.\n\n## Credential and configuration\n\nNone. There is no server, no connection to add, no `TOIL_GIT_*` variable and no\n`--connection` flag. The repository is the one the workspace (`--workspace`, else\n`TOIL_WORKSPACE`, else the working directory, else the MCP client's single root)\nsits in; outside one, every command fails with `Not a git repository` (or `GIT_NOT_FOUND`, when there is no git either).\n\nThese are the only commands that need git installed. toil finds it on PATH itself,\nskipping relative entries and the working directory, and runs it with no shell,\nno pager, no prompts and none of your environment's tokens. It also turns off what\na repository's config could make git run: external diff drivers, textconv filters,\nthe fsmonitor hook and signature checks. Without git on PATH they fail with\n`GIT_NOT_FOUND`, naming the PATH searched; nothing else in toil is affected.\n\n`toil git current-pr` is an alias of `toil bitbucket pr current`, which asks\nBitbucket for the open pull request from the current branch (see `bitbucket.md`).\n\n## Commands\n\n### `toil git status`\n\n`git status --porcelain`, as `{ staged, unstaged, untracked }`: lists of paths\nrelative to the repository root. A file with staged and unstaged changes is in\nboth. A rename reads `old -> new`, and a path git quotes stays quoted. MCP tool:\n`git_status`.\n\n### `toil git diff`\n\nThe uncommitted changes, parsed. MCP tool: `git_diff`.\n\n```bash\ntoil git diff\ntoil git diff --staged --file src/retry.ts\n```\n\n| Flag | Meaning |\n|------|---------|\n| `--staged` | The index against HEAD, instead of the working tree against the index |\n| `--file <path>` | One file, relative to the repository root |\n\nOutput: `{ files: [{ path, binary, truncated, hunks: [{ oldStart, oldCount,\nnewStart, newCount, lines }] }], truncated }`. Parsing stops after 5,000 lines of\ngit's output, with `truncated: true`. A git that fails, or a diff over 1 MB, gives\n`{ files: [], truncated: false }`.\n\n### `toil git log`\n\nRecent commits, newest first: `[{ hash, author, date, message }]`, `date` being\nthe author date in ISO 8601 and `message` the subject line. MCP tool: `git_log`.\n\n| Flag | Meaning |\n|------|---------|\n| `--count <n>` | How many (default 10). `0`, or anything that isn't a number, means no limit |\n| `--since <date>` | Anything git accepts: `2 weeks ago`, `2026-01-31` |\n\nA git that fails (a `--since` it can't read, an empty repository) gives `[]`.\n\n### `toil git branch`\n\n`git branch -a`, as `{ current, local, remote }`, remote names without their\n`remotes/` prefix (`origin/main`). Lines are kept as git prints them, so a branch\nchecked out in another worktree reads `+ name`, a detached HEAD is `current` as\n`(HEAD detached at \u2026)`, and `origin/HEAD -> origin/main` is a remote. MCP tool:\n`git_branch`.\n\n### `toil git report`\n\nCommits, lines and files changed on a branch, from `git log --numstat`. MCP tool:\n`git_report`.\n\n```bash\ntoil git report --since 2026-09-01\ntoil git report --base main --branch feature/retries --csv --out report.csv\n```\n\n| Flag | Meaning |\n|------|---------|\n| `--branch <name>` | The branch (default: the current one) |\n| `--base <ref>` | Report `base..branch`, or `base..HEAD` without `--branch` |\n| `--since <date>` | On or after this date: `YYYY-MM-DD` or anything git accepts |\n| `--until <date>` | Before this date. A plain `YYYY-MM-DD` is the start of that day in UTC, so that day itself is left out |\n| `--csv` | Also write one row per week and author, then a `TOTAL` row, as CSV. Needs `--out` |\n| `--out <file>` | The CSV file, a new one inside the workspace; toil never overwrites. Needs `--csv` |\n\nOutput: `{ branch, since, until, commits: [{ hash, date, author, message,\nfilesChanged, insertions, deletions, netLines }], weeks: [{ week, weekStart,\nweekEnd, authors, summary }], byAuthor, summary: { commitCount, totalInsertions,\ntotalDeletions, totalNetLines, totalFilesChanged } }`, plus `file` (the CSV's\nabsolute path) with `--csv`. Weeks run Monday to Sunday in UTC and are labelled by\nISO week (`2026-W40`). Absolute dates are applied again to each commit's author\ndate, since git's own range walks by committer date. A binary file counts 0 lines.\nThe CSV header is\n`week,week_start,author,commits,insertions,deletions,net_lines,files_changed`.\n\nA misspelt branch or base, or a date git can't read, gives an empty report.\n",
140334
- "github.md": '---\narea: github\ndescription: Pull requests, reviews, comments, checks, labels, assignees, issues and projects on GitHub and GitHub Enterprise Server\n---\n\n# GitHub and GitHub Enterprise Server (`github`)\n\nPull requests, reviews, comments, checks, labels, assignees, issues and Projects on\n**GitHub.com** and **GitHub Enterprise Server**, through the REST API and, for\nreview threads, PR status, auto-merge, the merge queue, drafts and Projects, the\nGraphQL API. The two differ only in host, so they\'re one area with a configurable\n`baseUrl`. Verification level: `unit`.\n\n**Supported versions:** The oldest GitHub Enterprise Server version toil supports hasn\'t been established. toil pins\nREST API version 2022-11-28 and uses GraphQL for review threads, PR status, auto-merge,\nthe merge queue, drafts and Projects. GitHub.com is always current; no Enterprise Server\nrelease has been verified yet. The auto-merge and merge-queue commands need a release\nthat has those features, and so do issue types, sub-issues and Projects (v2). A release\nwithout issue types just leaves `type` off each issue; one without sub-issues\n(`issue get --sub-issues`) or Projects (`project \u2026`) gets `UNSUPPORTED`, saying so.\n\n## Credential\n\nA **fine-grained personal access token**: Settings \u2192 Developer settings \u2192 Personal\naccess tokens \u2192 Fine-grained tokens, with access to the repositories you work on\n(pull requests, issues, contents and checks, read or write as needed). toil sends it as\n`Authorization: Bearer <token>`, with `Accept: application/vnd.github+json` and\n`X-GitHub-Api-Version: 2022-11-28`. There is no OAuth app, username, password or\nbrowser login.\n\nWhat each group of commands needs from the token:\n\n| Commands | Fine-grained token | Classic token |\n|----------|--------------------|---------------|\n| `issue list`, `issue search`, `issue get`, `issue history` | Issues: read, on the repository | `repo` (`public_repo` for public repositories only) |\n| `repo file` | Contents: read, on the repository | `repo` (`public_repo` for public repositories only) |\n| `project list`, `project fields`, `project items` | Projects: read, under the organization\'s permissions. A fine-grained token can\'t read a user\'s own projects | `read:project` (plus `repo` to see items from private repositories) |\n| Pull request, review, comment and check commands | Pull requests, contents and checks, read or write as needed | `repo` |\n\nA token without the Projects permission gets `AUTH` from the `project` commands,\nnaming the scope.\n\n## Configuration\n\n| Key | Env var | Required | Meaning |\n|-----|---------|----------|---------|\n| `baseUrl` | `TOIL_GITHUB_BASE_URL`, then `GITHUB_API_URL` | yes | The REST API root: `https://api.github.com`, or `https://ghe.imagile.dev/api/v3` for Enterprise Server |\n| `token` | `TOIL_GITHUB_TOKEN`, then `GITHUB_TOKEN` | yes | Fine-grained personal access token |\n| `owner` | `TOIL_GITHUB_OWNER` | no | Default owner (user or org) |\n| `repo` | `TOIL_GITHUB_REPO` | no | Default repository name |\n| `targetBranch` | `TOIL_GITHUB_TARGET_BRANCH` | no | Default base branch for `pr create` (`main` when unset) |\n| `writes` | `TOIL_GITHUB_WRITES` | no | `true` lets write commands run (with `--allow-write`) |\n\n**CI fallbacks:** in GitHub Actions, the default connection takes its token from\n`GITHUB_TOKEN` when `TOIL_GITHUB_TOKEN` isn\'t set, and its base URL from\n`GITHUB_API_URL` when `TOIL_GITHUB_BASE_URL` isn\'t set. Each sits directly below its\n`TOIL_GITHUB_*` variable and above the config file.\n\nThe GraphQL endpoint is derived from `baseUrl`: a trailing `/v3` is dropped and\n`/graphql` appended, so `https://api.github.com` uses `https://api.github.com/graphql`\nand `https://ghe.imagile.dev/api/v3` uses `https://ghe.imagile.dev/api/graphql`.\n\nEnvironment variables (CI, or a one-off shell):\n\n```bash\nexport TOIL_GITHUB_BASE_URL=https://ghe.imagile.dev/api/v3\nexport TOIL_GITHUB_TOKEN=<your fine-grained token>\n```\n\nOr `~/.toil/config.json`, with `owner`, `repo` and `targetBranch` usually set once\nunder `defaults.github`:\n\n```json\n{\n "version": 2,\n "connections": {\n "corp-github": { "area": "github", "baseUrl": "https://ghe.imagile.dev/api/v3" }\n },\n "defaults": { "github": { "connection": "corp-github", "owner": "imagile", "repo": "toil-probe" } }\n}\n```\n\nThe token never goes in this file; a plaintext one there is refused with\n`CONFIG_INVALID`. Run `toil connections add corp-github --area github` (or\n`toil connections login corp-github` for an existing connection) to keep it in the OS\ncredential store, or set `TOIL_GITHUB_TOKEN`.\n\n## Owner and repository\n\nEvery command except `repo create` needs an owner and a repository, which come\nfrom, in order:\n\n1. `--owner` and `--repo`, before or after the command (`toil github --owner imagile\n --repo toil-probe pr get 7`); on `pr create` the ones after the command win\n2. the first of the working folder\'s remotes whose host is this connection\'s host,\n of any name, trying `origin` first (so a fork\'s `upstream` counts)\n (`api.github.com` counts as `github.com`). `git@host:o/r`, `ssh://git@host[:port]/o/r`\n and `https://host[:port]/o/r` remotes are read, each with or without `.git`; an\n HTTPS remote with a user name in it isn\'t\n3. the connection\'s `owner` and `repo` (usually `defaults.github`)\n\nWith neither found, the command fails with "Could not determine GitHub owner/repo".\n`pr resolve` needs them too, though it acts by thread id alone. `repo create`\nreads only an explicit `--owner`, always as an organization (`POST /orgs/<owner>/repos`);\nwithout it the repository is created under the token\'s user.\n\n## Commands\n\nEvery command is `toil github <resource> <action> [ids...]`, and its MCP tool is the\npath with underscores (`github_pr_get`, `github_commit_checks`). Numbers (`<number>`,\n`<comment-id>`, `--line`) are read as whole numbers from the start of the text, so\n`12abc` is 12. Write commands need `writes` on the connection and `--allow-write`. The\ndeletes (`pr delete-comment`, `pr delete-review-comment`, `issue unlabel`,\n`pr remove-reviewers`, `issue unassign`) run on the CLI only and are never MCP tools.\nOwner, repo, labels and refs go into request paths as typed; a value that would make a\n`.` or `..` path segment is refused with `INVALID_INPUT`.\n\n- **Repositories:** `repo create` (`--name`, `--description`, `--private`,\n `--auto-init`), and `repo file <path>` (`--ref`), one file through the contents\n API: GitHub\'s record plus `text`, the file decoded as UTF-8 (null, with a\n `GITHUB_FILE_NOT_INLINED` warning, over 1 MB). A folder is refused.\n- **Issues:** each issue is GitHub\'s own, with the issue type in `type`, sub-issue\n counts in `sub_issues_summary` and the parent in `parent_issue_url`, where the server\n has them.\n - `issue create` (`--title`, `--body` or `--body-file <path>` with `-` for stdin,\n repeatable `--label` and `--assignee`).\n - `issue list` (`--state open|closed|all`, default `open`; repeatable `--label`, all\n of which must match; `--assignee`, `--type` with `none` or `*` too; `--sort\n created|updated|comments`, `--direction asc|desc`; `--updated-since <iso>`,\n GitHub\'s `since`). The issues endpoint mixes pull requests in; toil leaves them out\n (`pr list` has them).\n - `issue search --query <q>` (GitHub search syntax; `--sort`, `--order`,\n `--updated-since`). toil adds `is:issue`, and `updated:>=<iso>` with\n `--updated-since`, but not `--owner` or `--repo`: scope the query with `repo:`,\n `org:` or `user:`. GitHub serves only the first 1,000 results of a search, so past\n that toil stops with a `GITHUB_SEARCH_CAPPED` warning; a search GitHub timed out\n part of gets `GITHUB_SEARCH_INCOMPLETE`.\n - `issue get <number...>`, up to 100 numbers. One number returns the issue\n itself. Several return `{ issues, errors }`, read four at a time, where an issue\n GitHub can\'t find or answers with an error goes into `errors` as `{ number, code,\n message }`, with a `GITHUB_ISSUES_FAILED` warning; a bad token or a timeout still\n fails the call. `--sub-issues` adds `sub_issues`, each issue\'s sub-issues, one more\n request per issue.\n - `issue history <number>`: the issue\'s timeline, oldest first, as GitHub returns\n it: `closed` and `reopened` (with `state_reason`), `labeled`, `assigned`,\n `issue_type_added` and `issue_type_changed`, `sub_issue_added`,\n `cross-referenced` (the PRs that mention it), `commented` and the rest.\n - `--updated-since` reads a date the way `--created-after` does (a date alone is UTC\n midnight) and sends it as UTC to the second, `2025-01-31T00:00:00Z`.\n - Labels and assignees, on an issue or a pull request by its number: `issue label\n <number>` (repeatable `--label`), `issue unlabel <number> --label`, `issue assign\n <number>` and `issue unassign <number>` (repeatable `--assignee`). `pr label`,\n `pr unlabel`, `pr assign` and `pr unassign` are the same commands.\n- **Projects (v2):** GitHub\'s boards, read over GraphQL. They belong to an owner, so\n only `--owner` is read; `<project>` is the number in the project\'s URL.\n - `project list`: the owner\'s projects (`id`, `number`, `title`, `url`, `closed`, \u2026).\n - `project fields <project>`: each field\'s `id`, `name` and `dataType`, a\n single-select field\'s `options` (Status), and an iteration field\'s\n `configuration` with its `iterations` and `completedIterations`.\n - `project items <project>`: each item\'s `id`, `type` (`ISSUE`,\n `PULL_REQUEST`, `DRAFT_ISSUE`), `content` (number, title, state, url and\n repository) and `fieldValues`, each with its `field.name` and value (`text`,\n `number`, `date`, a single-select `name`, or an iteration\'s `title` and\n `startDate`). An item\'s first 100 values are read, with a\n `GITHUB_PROJECT_VALUES_TRUNCATED` warning past that.\n- **Pull requests** (`<number>` is the pull request number): `pr list` (`--state\n open|closed|all`, default `open`; `--head user:branch`, `--base`; `--author` and\n `--created-after`/`--created-before`, ISO 8601, are filtered as each page comes in,\n the author case-insensitively; a date alone is UTC midnight, a date-time with no zone\n local time; `--updated-since <iso>` keeps pull requests updated at or after it, and\n asks GitHub for the most recently updated first, `sort=updated&direction=desc`, so\n reading stops after the page that reaches an older one), `pr get <number>`\n (`--include reviews,checks,commits,files`, any of them, adds `included`, an object\n holding only the lists asked for, each GitHub\'s own records with every page read:\n `reviews`, `checks` (the check runs on the head commit, `head.sha`), `commits` and\n `files`; each list is one more request, more to page; GitHub serves at most 250\n commits and 3000 files of a pull request, and a list that long gets a\n `GITHUB_LIST_CAPPED` warning; an unknown name is `INVALID_INPUT`), `pr create`\n (`--title`, `--head`, `--base`\n defaulting to `targetBranch` then `main`, `--body`/`--body-file`, `--draft`),\n `pr update <number>` (`--title`, `--body`, `--base`), `pr merge <number>` (`--method\n merge|squash|rebase`, default `merge`, always sent; `--commit-title`,\n `--commit-message`), `pr close <number>`, `pr reopen <number>`, `pr draft <number>`,\n `pr ready <number>`.\n- **Merging:** `pr enable-auto-merge <number>` and `pr enqueue <number>` (`--method`,\n `--match-head-commit <sha>`), `pr disable-auto-merge <number>`.\n- **Comments:** `pr comments <number>` and `pr comment <number> --body` (the general\n comments, which work on an issue\'s number too; `issue comments` and `issue comment`\n are the same commands), `pr review-comments <number>`,\n `pr comment-inline <number>` (`--commit`, `--file`, `--line`, `--body`, `--side\n LEFT|RIGHT`, default `RIGHT`), `pr reply <number> <comment-id> --body`,\n `pr delete-comment <comment-id>`, `pr delete-review-comment <comment-id>`.\n- **Diff and files:** `pr diff <number>` returns `{ diff }`, the unified diff as text;\n `pr files <number>`.\n- **Reviews:** `pr reviews <number>`, `pr approve <number>` (`--body` optional),\n `pr request-changes <number>` (`--body` required), `pr reviewers <number>`,\n `pr threads <number>` (thread ids for `pr resolve`; the first 100 threads with a\n `GITHUB_REVIEW_THREADS_TRUNCATED` warning past that, and the first 10 comments of\n each), `pr resolve <thread-id>`, `pr add-reviewers <number>` and\n `pr remove-reviewers <number>` (repeatable `--reviewer` and `--team-reviewer`, at\n least one).\n- **Status:** `commit status <ref>` (the combined status; GitHub\'s first 30 statuses),\n `commit checks <ref>`, `pr status <number>` (review decision, mergeability, draft\n and auto-merge state, and the first 100 checks counted into `checks.passed`,\n `failed`, `pending` and `other`).\n\nLists page 100 at a time until a short page, and stop with an error after 1,000 pages.\nEvery list (`pr list`, `pr files`, `pr comments`, `pr review-comments`, `pr reviews`,\n`commit checks`, `issue list`, `issue search`, `issue history` and the three `project`\nlists) reads every page by default. `--limit <n>` stops after `n` items and sets\n`meta.page.nextCursor`; pass it back as `--cursor` with the same `--limit` for the next\n`n`, until `nextCursor` is `null`. On `pr list`, `--limit` counts the pull requests that\npass `--author` and the date filters, `--updated-since` included.\n\n```bash\ntoil github issue list --state all --sort updated --direction asc --updated-since 2025-01-31T00:00:00Z --limit 100\ntoil github issue get 9 10 --sub-issues\ntoil github --owner imagile project items 3\ntoil github pr list --state all --author octo-dev\ntoil github pr list --state all --updated-since 2025-01-31T00:00:00Z --limit 50\ntoil github pr get 7 --include reviews,checks\ntoil github repo file .github/CODEOWNERS\ntoil github --owner imagile --repo toil-probe pr status 7\ntoil github pr create --title "Add the probe" --head feature --body-file pr.md --allow-write\n```\n\n## Checking a dossier\n\n`check-dossier` checks the call\'s dossier: each owner it names (`owner`, per repo or not, and `owners`) is a user or organization, and each repository (`repo`) exists under its owner. It\'s `toil github check-dossier` (`--dossier <name|file>`, or the dossier the folder resolves to), and it returns `{ dossier, connection, env, ok, checked, checks, unchecked }`, one check per value with its key path. The CLI exits 1 when one is missing. A failure other than not-found (a bad token, an unreachable host) fails the command. Read only.\n',
140437
+ "github.md": '---\narea: github\ndescription: Pull requests, reviews, comments, checks, labels, assignees, issues and projects on GitHub and GitHub Enterprise Server\n---\n\n# GitHub and GitHub Enterprise Server (`github`)\n\nPull requests, reviews, comments, checks, labels, assignees, issues and Projects on\n**GitHub.com** and **GitHub Enterprise Server**, through the REST API and, for\nreview threads, PR status, auto-merge, the merge queue, drafts and Projects, the\nGraphQL API. The two differ only in host, so they\'re one area with a configurable\n`baseUrl`. Verification level: `unit`.\n\n**Supported versions:** The oldest GitHub Enterprise Server version toil supports hasn\'t been established. toil pins\nREST API version 2022-11-28 and uses GraphQL for review threads, PR status, auto-merge,\nthe merge queue, drafts and Projects. GitHub.com is always current; no Enterprise Server\nrelease has been verified yet. The auto-merge and merge-queue commands need a release\nthat has those features, and so do issue types, sub-issues and Projects (v2). A release\nwithout issue types just leaves `type` off each issue; one without sub-issues\n(`issue get --sub-issues`) or Projects (`project \u2026`) gets `UNSUPPORTED`, saying so.\n\n## Credential\n\nA **fine-grained personal access token**: Settings \u2192 Developer settings \u2192 Personal\naccess tokens \u2192 Fine-grained tokens, with access to the repositories you work on\n(pull requests, issues, contents and checks, read or write as needed). toil sends it as\n`Authorization: Bearer <token>`, with `Accept: application/vnd.github+json` and\n`X-GitHub-Api-Version: 2022-11-28`. There is no OAuth app, username, password or\nbrowser login.\n\nWhat each group of commands needs from the token:\n\n| Commands | Fine-grained token | Classic token |\n|----------|--------------------|---------------|\n| `issue list`, `issue search`, `issue get`, `issue history` | Issues: read, on the repository | `repo` (`public_repo` for public repositories only) |\n| `repo file` | Contents: read, on the repository | `repo` (`public_repo` for public repositories only) |\n| `project list`, `project fields`, `project items` | Projects: read, under the organization\'s permissions. A fine-grained token can\'t read a user\'s own projects | `read:project` (plus `repo` to see items from private repositories) |\n| Pull request, review, comment and check commands | Pull requests, contents and checks, read or write as needed | `repo` |\n\nA token without the Projects permission gets `AUTH` from the `project` commands,\nnaming the scope.\n\n## Configuration\n\n| Key | Env var | Required | Meaning |\n|-----|---------|----------|---------|\n| `baseUrl` | `TOIL_GITHUB_BASE_URL`, then `GITHUB_API_URL` | yes | The REST API root: `https://api.github.com`, or `https://ghe.imagile.dev/api/v3` for Enterprise Server |\n| `token` | `TOIL_GITHUB_TOKEN`, then `GITHUB_TOKEN` | yes | Fine-grained personal access token |\n| `owner` | `TOIL_GITHUB_OWNER` | no | Default owner (user or org) |\n| `repo` | `TOIL_GITHUB_REPO` | no | Default repository name |\n| `targetBranch` | `TOIL_GITHUB_TARGET_BRANCH` | no | Default base branch for `pr create` (`main` when unset) |\n| `writes` | `TOIL_GITHUB_WRITES` | no | `true` lets write commands run (with `--allow-write`) |\n\n**CI fallbacks:** in GitHub Actions, the default connection takes its token from\n`GITHUB_TOKEN` when `TOIL_GITHUB_TOKEN` isn\'t set, and its base URL from\n`GITHUB_API_URL` when `TOIL_GITHUB_BASE_URL` isn\'t set. Each sits directly below its\n`TOIL_GITHUB_*` variable and above the config file.\n\nThe GraphQL endpoint is derived from `baseUrl`: a trailing `/v3` is dropped and\n`/graphql` appended, so `https://api.github.com` uses `https://api.github.com/graphql`\nand `https://ghe.imagile.dev/api/v3` uses `https://ghe.imagile.dev/api/graphql`.\n\nEnvironment variables (CI, or a one-off shell):\n\n```bash\nexport TOIL_GITHUB_BASE_URL=https://ghe.imagile.dev/api/v3\nexport TOIL_GITHUB_TOKEN=<your fine-grained token>\n```\n\nOr `~/.toil/config.json`, with `owner`, `repo` and `targetBranch` usually set once\nunder `defaults.github`:\n\n```json\n{\n "version": 2,\n "connections": {\n "corp-github": { "area": "github", "baseUrl": "https://ghe.imagile.dev/api/v3" }\n },\n "defaults": { "github": { "connection": "corp-github", "owner": "imagile", "repo": "toil-probe" } }\n}\n```\n\nThe token never goes in this file; a plaintext one there is refused with\n`CONFIG_INVALID`. Run `toil connections add corp-github --area github` (or\n`toil connections login corp-github` for an existing connection) to keep it in the OS\ncredential store, or set `TOIL_GITHUB_TOKEN`.\n\n## Owner and repository\n\nEvery command except `repo create` needs an owner and a repository, which come\nfrom, in order:\n\n1. `--owner` and `--repo`, before or after the command (`toil github --owner imagile\n --repo toil-probe pr get 7`); on `pr create` the ones after the command win\n2. the first of the working folder\'s remotes whose host is this connection\'s host,\n of any name, trying `origin` first (so a fork\'s `upstream` counts)\n (`api.github.com` counts as `github.com`). `git@host:o/r`, `ssh://git@host[:port]/o/r`\n and `https://host[:port]/o/r` remotes are read, each with or without `.git`; an\n HTTPS remote with a user name in it isn\'t\n3. the connection\'s `owner` and `repo` (usually `defaults.github`)\n\nWith neither found, the command fails with "Could not determine GitHub owner/repo".\n`pr resolve` needs them too, though it acts by thread id alone. `repo create`\nreads only an explicit `--owner`, always as an organization (`POST /orgs/<owner>/repos`);\nwithout it the repository is created under the token\'s user.\n\n## Commands\n\nEvery command is `toil github <resource> <action> [ids...]`, and its MCP tool is the\npath with underscores (`github_pr_get`, `github_commit_checks`). Numbers (`<number>`,\n`<comment-id>`, `--line`) are read as whole numbers from the start of the text, so\n`12abc` is 12. Write commands need `writes` on the connection and `--allow-write`. The\ndeletes (`pr delete-comment`, `pr delete-review-comment`, `issue unlabel`,\n`pr remove-reviewers`, `issue unassign`) run on the CLI only and are never MCP tools.\nOwner, repo, labels and refs go into request paths as typed; a value that would make a\n`.` or `..` path segment is refused with `INVALID_INPUT`.\n\n- **Repositories:** `repo create` (`--name`, `--description`, `--private`,\n `--auto-init`), and `repo file <path>` (`--ref`), one file through the contents\n API: GitHub\'s record plus `text`, the file decoded as UTF-8 (null, with a\n `GITHUB_FILE_NOT_INLINED` warning, over 1 MB). A folder is refused.\n- **Issues:** each issue is GitHub\'s own, with the issue type in `type`, sub-issue\n counts in `sub_issues_summary` and the parent in `parent_issue_url`, where the server\n has them.\n - `issue create` (`--title`, `--body` or `--body-file <path>` with `-` for stdin,\n repeatable `--label` and `--assignee`).\n - `issue list` (`--state open|closed|all`, default `open`; repeatable `--label`, all\n of which must match; `--assignee`, `--type` with `none` or `*` too; `--sort\n created|updated|comments`, `--direction asc|desc`; `--updated-since <iso>`,\n GitHub\'s `since`). The issues endpoint mixes pull requests in; toil leaves them out\n (`pr list` has them).\n - `issue search --query <q>` (GitHub search syntax; `--sort`, `--order`,\n `--updated-since`). toil adds `is:issue`, and `updated:>=<iso>` with\n `--updated-since`, but not `--owner` or `--repo`: scope the query with `repo:`,\n `org:` or `user:`. GitHub serves only the first 1,000 results of a search, so past\n that toil stops with a `GITHUB_SEARCH_CAPPED` warning; a search GitHub timed out\n part of gets `GITHUB_SEARCH_INCOMPLETE`.\n - `issue get <number...>`, up to 100 numbers. One number returns the issue\n itself. Several return `{ issues, errors }`, read four at a time, where an issue\n GitHub can\'t find or answers with an error goes into `errors` as `{ number, code,\n message }`, with a `GITHUB_ISSUES_FAILED` warning; a bad token or a timeout still\n fails the call. `--sub-issues` adds `sub_issues`, each issue\'s sub-issues, one more\n request per issue.\n - `issue history <number>`: the issue\'s timeline, oldest first, as GitHub returns\n it: `closed` and `reopened` (with `state_reason`), `labeled`, `assigned`,\n `issue_type_added` and `issue_type_changed`, `sub_issue_added`,\n `cross-referenced` (the PRs that mention it), `commented` and the rest.\n - `--updated-since` reads a date the way `--created-after` does (a date alone is UTC\n midnight) and sends it as UTC to the second, `2025-01-31T00:00:00Z`.\n - Labels and assignees, on an issue or a pull request by its number: `issue label\n <number>` (repeatable `--label`), `issue unlabel <number> --label`, `issue assign\n <number>` and `issue unassign <number>` (repeatable `--assignee`). `pr label`,\n `pr unlabel`, `pr assign` and `pr unassign` are the same commands.\n- **Projects (v2):** GitHub\'s boards, read over GraphQL. They belong to an owner, so\n only `--owner` is read; `<project>` is the number in the project\'s URL.\n - `project list`: the owner\'s projects (`id`, `number`, `title`, `url`, `closed`, \u2026).\n - `project fields <project>`: each field\'s `id`, `name` and `dataType`, a\n single-select field\'s `options` (Status), and an iteration field\'s\n `configuration` with its `iterations` and `completedIterations`.\n - `project items <project>`: each item\'s `id`, `type` (`ISSUE`,\n `PULL_REQUEST`, `DRAFT_ISSUE`), `content` (number, title, state, url and\n repository) and `fieldValues`, each with its `field.name` and value (`text`,\n `number`, `date`, a single-select `name`, or an iteration\'s `title` and\n `startDate`). An item\'s first 100 values are read, with a\n `GITHUB_PROJECT_VALUES_TRUNCATED` warning past that.\n- **Pull requests** (`<number>` is the pull request number): `pr list` (`--state\n open|closed|all`, default `open`; `--head user:branch`, `--base`; `--author` and\n `--created-after`/`--created-before`, ISO 8601, are filtered as each page comes in,\n the author case-insensitively; a date alone is UTC midnight, a date-time with no zone\n local time; `--updated-since <iso>` keeps pull requests updated at or after it, and\n asks GitHub for the most recently updated first, `sort=updated&direction=desc`, so\n reading stops after the page that reaches an older one), `pr get <number>`\n (`--include reviews,checks,commits,files`, any of them, adds `included`, an object\n holding only the lists asked for, each GitHub\'s own records with every page read:\n `reviews`, `checks` (the check runs on the head commit, `head.sha`), `commits` and\n `files`; each list is one more request, more to page; GitHub serves at most 250\n commits and 3000 files of a pull request, and a list that long gets a\n `GITHUB_LIST_CAPPED` warning; an unknown name is `INVALID_INPUT`), `pr create`\n (`--title`, `--head`, `--base`\n defaulting to `targetBranch` then `main`, `--body`/`--body-file`, `--draft`),\n `pr update <number>` (`--title`, `--body`, `--base`), `pr merge <number>` (`--method\n merge|squash|rebase`, default `merge`, always sent; `--commit-title`,\n `--commit-message`), `pr close <number>`, `pr reopen <number>`, `pr draft <number>`,\n `pr ready <number>`.\n- **Merging:** `pr enable-auto-merge <number>` and `pr enqueue <number>` (`--method`,\n `--match-head-commit <sha>`), `pr disable-auto-merge <number>`.\n- **Comments:** `pr comments <number>` and `pr comment <number> --body` (the general\n comments, which work on an issue\'s number too; `issue comments` and `issue comment`\n are the same commands), `pr review-comments <number>`,\n `pr comment-inline <number>` (`--commit`, `--file`, `--line`, `--body`, `--side\n LEFT|RIGHT`, default `RIGHT`), `pr reply <number> <comment-id> --body`,\n `pr delete-comment <comment-id>`, `pr delete-review-comment <comment-id>`.\n- **Diff and files:** `pr diff <number>` returns `{ diff }`, the unified diff as text;\n `pr files <number>`.\n- **Reviews:** `pr reviews <number>`, `pr approve <number>` (`--body` optional),\n `pr request-changes <number>` (`--body` required), `pr reviewers <number>`,\n `pr threads <number>` (thread ids for `pr resolve`; the first 100 threads with a\n `GITHUB_REVIEW_THREADS_TRUNCATED` warning past that, and the first 10 comments of\n each), `pr resolve <thread-id>`, `pr add-reviewers <number>` and\n `pr remove-reviewers <number>` (repeatable `--reviewer` and `--team-reviewer`, at\n least one).\n- **Status:** `commit status <ref>` (the combined status; GitHub\'s first 30 statuses),\n `commit checks <ref>`, `pr status <number>` (review decision, mergeability, draft\n and auto-merge state, and the first 100 checks counted into `checks.passed`,\n `failed`, `pending` and `other`).\n\nLists page 100 at a time until a short page, and stop with an error after 1,000 pages.\nEvery list (`pr list`, `pr files`, `pr comments`, `pr review-comments`, `pr reviews`,\n`commit checks`, `issue list`, `issue search`, `issue history` and the three `project`\nlists) reads every page by default. `--limit <n>` stops after `n` items and sets\n`meta.page.nextCursor`; pass it back as `--cursor` with the same `--limit` for the next\n`n`, until `nextCursor` is `null`. On `pr list`, `--limit` counts the pull requests that\npass `--author` and the date filters, `--updated-since` included.\n\n```bash\ntoil github issue list --state all --sort updated --direction asc --updated-since 2025-01-31T00:00:00Z --limit 100\ntoil github issue get 9 10 --sub-issues\ntoil github --owner imagile project items 3\ntoil github pr list --state all --author octo-dev\ntoil github pr list --state all --updated-since 2025-01-31T00:00:00Z --limit 50\ntoil github pr get 7 --include reviews,checks\ntoil github repo file .github/CODEOWNERS\ntoil github --owner imagile --repo toil-probe pr status 7\ntoil github pr create --title "Add the probe" --head feature --body-file pr.md --allow-write\n```\n\n## Ticket the work\n\nBefore starting work no ticket covers, rank your open issues against it:\n\n```bash\ntoil github issue search --query "repo:imagile/payments-web is:open assignee:@me" | toil util owi map | toil util owi similar --query "Card payments time out at checkout"\n```\n\nThen ask the person, as `core.md`, **Ticket the work**, says: attach the work to a\nmatch (nothing is written), create a sub-task under it, or create a new ticket. toil\nhas no sub-issue command, so a sub-task is a new issue that names its parent in the\nbody (`Part of #12`); a new ticket is\n`toil github issue create --title "<text>" --allow-write`, in the repository the\ndossier names. Both are writes, made only on the person\'s yes.\n\n## Checking a dossier\n\n`check-dossier` checks the call\'s dossier: each owner it names (`owner`, per repo or not, and `owners`) is a user or organization, and each repository (`repo`) exists under its owner. It\'s `toil github check-dossier` (`--dossier <name|file>`, or the dossier the folder resolves to), and it returns `{ dossier, connection, env, ok, checked, checks, unchecked }`, one check per value with its key path. The CLI exits 1 when one is missing. A failure other than not-found (a bad token, an unreachable host) fails the command. Read only.\n',
140335
140438
  "install.md": "---\ndescription: Installing toil from npm or from a clone with no npm install, the toil alias for a clone, and installing this skill for Codex, GitHub Copilot or Claude Code\n---\n\n# Installing toil\n\nCheck first: if `toil version` prints an envelope with `\"ok\": true`, toil is installed\nand nothing here is needed. If `toil` isn't found but a clone of the toil repository is\non the machine, `node <clone>/dist/toil.js version` is the same thing.\n\ntoil needs **Node.js 24.14 or later** (`node --version`) and nothing else: no\nexecutable, no native module, no install script and no admin rights. On an older Node\nevery command returns `UNSUPPORTED_NODE`. Windows, macOS and Linux all work the same.\n\n## From npm (recommended)\n\n```bash\nnpm install -g @imagile-dev/toil\ntoil version\n```\n\nWith no global install, `npx -y @imagile-dev/toil version` runs it on demand. Each\nGitHub release also carries the packed `.tgz` for offline or mirrored installs:\n`npm install -g ./imagile-dev-toil-<version>.tgz`.\n\n**toil is alpha: APIs and flags may change before 1.0.** Releases are published under\nnpm's `alpha` tag, which `latest` follows until 1.0.\n\n## From a clone, with no npm install\n\nFor a machine that can reach the git host but not the npm registry. Needs Node and\ngit. A person setting up their own machine can do it all in one command, which\nbuilds the clone, adds the alias below and prints `toil version`\n(the build runs `npm ci`; with no registry, add `--skip-build` to use the committed\nbundle as it is):\n\n```bash\ngit clone https://github.com/imagile-dev/toil.git && cd toil && node scripts/setup.mjs\n```\n\nStep by step:\n\n```bash\ngit clone https://github.com/imagile-dev/toil.git\nnode toil/dist/toil.js version\n```\n\n`dist/toil.js` is committed with the bundle it runs, `dist/toil-lib.js`, and they are\nthe **last released toil**: each release rebuilds them, and nothing else changes\nthem, so they are the same files that release ships on npm.\nNewer commits on `main` are in a clone's source but not in its bundle until the next\nrelease. They import only Node's built-ins, so there is nothing to install.\n\nTo type `toil` instead of `node <clone>/dist/toil.js`, add an alias to the shell\nprofile, once:\n\n| Shell | Run | Edits |\n|-------|-----|-------|\n| bash, zsh | `node toil/dist/toil.js setup alias` | `~/.bashrc` or `~/.zshrc`, by `SHELL` (`--shell bash` or `--shell zsh` to choose) |\n| PowerShell | `node toil/dist/toil.js setup alias --profile $PROFILE` | The profile of the PowerShell you ran it in |\n\nThen open a new terminal and run `toil version`. `--profile <file>` names any other\nprofile (macOS bash login shells read `~/.bash_profile`). The alias is a shell\nfunction between two marker lines; nothing else in the file changes, and running it\nagain updates it in place. `node toil/dist/toil.js setup remove-alias`, with the same\nflags, takes it out.\n\n- **An agent's shell may not read the profile.** When `toil` isn't found there, run\n `node <clone>/dist/toil.js` with the same arguments; it's the same command.\n- **Windows PowerShell's default execution policy runs no profile.** If `toil` isn't\n found after opening a new PowerShell, call `node <clone>/dist/toil.js` directly.\n- **Update** with `git -C toil pull`, which brings the newest release. There is\n nothing to rebuild.\n\n## Installing this skill\n\ntoil carries this skill inside itself, so the copy it installs always matches the\ntoil that runs it. Install it once, for the agent you use:\n\n```bash\ntoil skill install --allow-write\ntoil skill install --agent github-copilot --scope project --allow-write\ntoil skill install --claude --allow-write\n```\n\n| `--agent` | `--scope user` (the default) | `--scope project` |\n|-----------|------------------------------|-------------------|\n| `codex` (the default; GitHub Copilot reads it too) | `~/.agents/skills/toil` | `.agents/skills/toil` |\n| `github-copilot` | `~/.copilot/skills/toil` | `.github/skills/toil` |\n| `claude-code` (`--claude`) | `~/.claude/skills/toil` | `.claude/skills/toil` |\n\nA project-scope copy describes your own config, so add the folder (for example\n`.github/skills/toil/`) to `.gitignore`.\n\nProject scope is the root of the repository you're in. Installing writes files\noutside the workspace, so it's CLI only and needs `--allow-write`. Every reference\nfile is installed, so an area you set up later is already documented.\n\n**The installed skill keeps itself current; there is nothing to update by hand.** The\ndescription in the installed `SKILL.md` names the areas and database engines you have\nconnections for (names only, never a host or a credential), so an agent reaches for\ntoil when a task touches one of them. Any toil command that loads config, on the CLI\nor over MCP, rewrites every copy toil installed when that command changed the config\nfile (`toil connections add`, `login`, `remove`, `writes`, `default`, `toil skills\nmarketplace add` and `remove`), and when the copy was written by another toil\nversion. Nothing else in a skills folder is ever touched. This is one of the writes\nthat need no `--allow-write`: `core.md`, under **Writes**, says why, and how to avoid\nit. Connections that only `TOIL_*` env vars define are named when they're set in the\nprocess that writes the skill, and the output says which. With no connections, the\ndescription is the general one.\n\n`toil skill show` (`skill_show` over MCP) prints the description toil would write now\nand every installed copy, with its version and whether it's current.\n\ntoil only ever rewrites a `toil` folder it installed itself. One copied by hand, or\ninstalled by a marketplace, is left exactly as it is, and `toil skill install` refuses\nto replace it: move it aside first.\n\nOther ways in, for agents toil doesn't write to:\n\n- **Claude Code**, from the plugin marketplace in the repository:\n `claude plugin marketplace add imagile-dev/toil`, then\n `claude plugin install toil@toil` (or `/plugin marketplace add imagile-dev/toil` and\n `/plugin install toil@toil` in a session). From a clone, pass its path instead of\n `imagile-dev/toil`. This copy carries the general description, and toil doesn't\n keep it current.\n- **Any installer that reads `skills/<name>/SKILL.md` from a git repository**: point it\n at `https://github.com/imagile-dev/toil`.\n\n## Next\n\nConnect toil to a tool: each area's file (`jira.md`, `db.md`, \u2026) gives its credential,\nits env vars and its config. To run toil as an MCP server, see `mcp.md`.\n",
140336
140439
  "jenkins.md": '---\narea: jenkins\ndescription: Jenkins jobs, builds, console logs and triggering builds, on one or more named instances\n---\n\n# Jenkins (`jenkins`)\n\nJobs, builds, console logs and the build queue on **Jenkins**, through its classic\nremote access API (`/api/json` with `tree`, `consoleText`, `/queue/item`). Every\ncommand reads except `pipeline run`, which triggers a build. Verification level:\n`unit`.\n\n**Supported versions:** The oldest Jenkins version toil supports hasn\'t been established. toil\ncalls the classic remote access API with a user name and API token sent as Basic auth.\nNo release has been verified yet.\n\n## Credential\n\nA Jenkins **API token** and the user name it belongs to: in Jenkins, your user name \u2192\nSecurity \u2192 API Token \u2192 Add new token. toil sends `Authorization: Basic\nbase64(username:apiToken)`; both parts are required. No CSRF crumb is requested,\nand there is no password or browser login.\n\n## Configuration\n\n| Key | Env var | Required | Meaning |\n|-----|---------|----------|---------|\n| `baseUrl` | `TOIL_JENKINS_BASE_URL` | yes | Jenkins server root, e.g. `https://jenkins.imagile.dev` (keep any context path) |\n| `username` | `TOIL_JENKINS_USERNAME` | yes | Jenkins user name the API token belongs to |\n| `apiToken` | `TOIL_JENKINS_API_TOKEN` | yes | Jenkins API token |\n| `instance` | `TOIL_JENKINS_INSTANCE` | no | The name `--instance` selects this connection by, when it isn\'t the connection\'s own name |\n\nThere\'s no CI fallback variable. Environment variables (CI, or a one-off shell)\nconfigure the default connection:\n\n```bash\nexport TOIL_JENKINS_BASE_URL=https://jenkins.imagile.dev\nexport TOIL_JENKINS_USERNAME=ci-bot\nexport TOIL_JENKINS_API_TOKEN=<your API token>\n```\n\n## Named instances\n\nEach Jenkins server is its own connection. `--instance <name>` (on the group:\n`toil jenkins --instance ephemeral pipeline list`, or the `instance` field over MCP)\nselects the jenkins connection with that name, or the one whose `instance` setting is\nthat name. An unknown name is `INVALID_INPUT`, listing the ones toil knows. Without\n`--instance`, the area\'s default connection is used.\n\n```json\n{\n "version": 2,\n "connections": {\n "jenkins": { "area": "jenkins", "baseUrl": "https://jenkins.imagile.dev", "username": "ci-bot" },\n "ephemeral": { "area": "jenkins", "baseUrl": "https://jenkins-tmp.imagile.dev", "username": "tmp-user" }\n },\n "defaults": { "jenkins": { "connection": "jenkins" } }\n}\n```\n\nThe API token never goes in this file; a plaintext one there is refused with\n`CONFIG_INVALID`. Add an instance with `toil connections add ephemeral --area\njenkins`, which asks for each setting and keeps the token in the OS credential\nstore; remove one with `toil connections remove ephemeral`. In CI, define one with\n`TOIL_CONN_EPHEMERAL_AREA=jenkins` and `TOIL_CONN_EPHEMERAL_BASE_URL`, `_USERNAME`\nand `_API_TOKEN`.\n\n- `instance list`: List configured Jenkins instances. It is `toil connections list\n --area jenkins`: every jenkins connection\'s name, host, whether it\'s the default,\n whether writes are on, and where each setting came from, never a secret. Over MCP,\n call `connections_list` with `area: "jenkins"`.\n- `instance add <name>`: CLI only. It is `toil connections add <name> --area\n jenkins`, asking for each setting on a terminal and keeping the token in the OS\n credential store. It takes the name as an argument and accepts none of the\n contract\'s `--name`, `--base-url`, `--username`, `--api-token` and `--force` flags.\n- `instance remove <name>`: CLI only. It is `toil connections remove <name> --area\n jenkins`, which also deletes the token from the OS credential store and refuses a\n connection to another area. It takes the name as an argument, not `--name`.\n\n## Commands\n\nJob names with folders are written `folder/job` (`platform/api-build`); each level\nbecomes `/job/<segment>`, percent-encoded.\n\n- `pipeline list`: List all jobs on the Jenkins instance (or within a folder, `--folder parent/child`).\n- `pipeline get <name>`: Get details for a specific job, with its last 10 builds.\n- `pipeline run <name>`: Trigger a build. It writes, so it needs `writes: true`\n on the connection and `--allow-write`. Each `--parameter key=value` (repeatable)\n sends the build to `buildWithParameters`; without one it goes to `build`, even for\n a parameterized job. Without `--wait`, `data` is `{ queueItemId }`. With `--wait`\n it polls every `--poll` seconds (default 10) until the build leaves the queue, then\n until it finishes, giving each phase `--timeout` seconds (default 600), and returns\n the build. A build whose result is set and isn\'t `SUCCESS` is still returned as\n `data` with `ok: true`, but the CLI exits 1, and `meta.warnings` has a\n `JENKINS_BUILD_NOT_SUCCESSFUL` warning (over MCP, check the warning or\n `data.result`).\n The command\'s time limit is 21 minutes (`TOIL_TIMEOUT_MS` overrides it).\n `--timeout` and `--poll` are checked only after the build was triggered.\n- `pipeline runs <name>`: List recent builds for a job (`--limit`, default 25).\n Jenkins\' `builds` list holds only the newest 100.\n- `run get <name> <number>`: Get details for a specific build.\n- `run logs <name> <number>`: Fetch console log for a build (consider --output-file for large\n logs); `data` is `{ log }`, the whole text.\n\nThe build number, `--limit`, `--timeout` and `--poll` are read as whole numbers from the\nstart of the text, so `12abc` is 12.\n\n```bash\ntoil jenkins pipeline list --folder platform\ntoil jenkins --instance ephemeral pipeline runs platform/api-build --limit 5\ntoil jenkins pipeline run api-build --parameter BRANCH=main --wait --allow-write\n```\n',
140337
- "jira-cloud.md": '---\narea: jira-cloud\ndescription: Issues, JQL search, transitions, comments, worklogs, labels, links, attachments, custom fields, projects, users, boards and sprints on Jira Cloud\n---\n\n# Jira Cloud (`jira-cloud`)\n\nIssues, JQL search, transitions, comments, worklogs, labels, links, attachments,\ncustom fields, projects, users, boards and sprints on **Jira Cloud**\n(`https://<your-site>.atlassian.net`, REST API 3 and the Agile REST API 1.0). Built\nfrom Atlassian\'s API documentation and never run against a live site. Verification\nlevel: `unit`.\n\nFor Jira Data Center or Server, use the `jira` area instead. The two are separate\nareas because their APIs differ: Cloud names people by **accountId**, not username,\nand its rich text is **Atlassian Document Format** (ADF), not a string.\n\n**Supported versions:** The oldest Jira Cloud version toil supports hasn\'t been established. Jira\nCloud is always current. toil calls REST API 3 (`/rest/api/3`, with the enhanced JQL\nsearch at `/rest/api/3/search/jql`) and the Agile REST API 1.0, with an Atlassian\naccount email and API token sent as Basic auth. Nothing has been run against a live\nsite yet.\n\n## Credential\n\nAn **Atlassian account API token** plus that account\'s **email address**. Create\nthe token at https://id.atlassian.com/manage-profile/security/api-tokens (Atlassian\naccount \u2192 Security \u2192 API tokens \u2192 Create API token). toil sends\n`Authorization: Basic base64(<email>:<apiToken>)`, as Atlassian documents for\nscripts. There is no password, OAuth app or browser login. The token acts with the\naccount\'s own permissions, so a read sees what that account can see.\n\nIf the email and token don\'t match, Jira Cloud may treat the call as anonymous\nrather than refuse it: a 401 is `AUTH`, but a missing issue can also surface as\n`NOT_FOUND`, and a search as no results. When a call that should work finds nothing,\ncheck `email` first.\n\n## Configuration\n\n| Key | Env var | Required | Meaning |\n|-----|---------|----------|---------|\n| `baseUrl` | `TOIL_JIRA_CLOUD_BASE_URL` | yes | Jira Cloud site root, `https://<your-site>.atlassian.net` |\n| `email` | `TOIL_JIRA_CLOUD_EMAIL` | yes | Email address of the Atlassian account the token belongs to |\n| `apiToken` | `TOIL_JIRA_CLOUD_API_TOKEN` | yes | Atlassian account API token (a secret) |\n| `customFields` | `TOIL_JIRA_CLOUD_CUSTOM_FIELDS` (JSON) | no | Custom fields addressable by friendly name; see **Custom fields** |\n| `project` | `TOIL_JIRA_CLOUD_PROJECT` | no | Default project for `issue create` |\n| `issueType` | `TOIL_JIRA_CLOUD_ISSUE_TYPE` | no | Default issue type for `issue create` (`Task` when unset) |\n| `priority` | `TOIL_JIRA_CLOUD_PRIORITY` | no | Default priority for `issue create` |\n| `writes` | `TOIL_JIRA_CLOUD_WRITES` | no | `true` lets write commands run (with `--allow-write`) |\n\nThere is no CI fallback variable. The examples use the placeholder\n`https://jira-cloud.imagile.dev`, which never resolves; your own site is\n`https://<your-site>.atlassian.net`.\n\n```bash\nexport TOIL_JIRA_CLOUD_BASE_URL=https://jira-cloud.imagile.dev\nexport TOIL_JIRA_CLOUD_EMAIL=you@example.com\nexport TOIL_JIRA_CLOUD_API_TOKEN=<your API token>\n```\n\nOr `~/.toil/config.json`, with `project`, `issueType` and `priority` usually set once\nunder `defaults.jira-cloud`:\n\n```json\n{\n "version": 2,\n "connections": {\n "imagile-cloud": { "area": "jira-cloud", "baseUrl": "https://jira-cloud.imagile.dev", "email": "you@example.com", "writes": true }\n },\n "defaults": { "jira-cloud": { "connection": "imagile-cloud", "project": "PROJ" } }\n}\n```\n\nThe token never goes in this file; a plaintext one there is refused with\n`CONFIG_INVALID`. Run `toil connections add imagile-cloud --area jira-cloud` (or\n`toil connections login imagile-cloud`) to keep it in the OS credential store, or set\n`TOIL_JIRA_CLOUD_API_TOKEN`. Env vars always win over the file.\n\n## Commands\n\nEvery command also takes `--connection <name>`. Write commands (marked \u270E) need\n`writes: true` on the connection **and** `--allow-write`. Names and flags match\n`jira` wherever the operation is the same. MCP tools are named after the path, with\nspaces and hyphens as underscores (`jira_cloud_issue_get`, `jira_cloud_user_search`).\n\n| Command | Arguments and flags | Returns |\n|---------|-------|---------|\n| `issue get` | `<key...>` (up to 100) | The issue as Jira returns it, registered custom fields under their friendly names, plus `descriptionText`. With several keys, `{ issues, errors }` |\n| `issue history` | `<key> --limit --cursor` | The issue\'s change history, oldest first: `id`, `author`, `created`, `items` |\n| `issue create` \u270E | `--project --type --summary --description --priority --assignee <account-id> --labels --parent --field (repeatable) --fields-file --input-file` | The created issue, read back, plus `descriptionText` |\n| `issue update` \u270E | `<key> --summary --description --priority --assignee <account-id> --labels --field --fields-file --input-file` | `{ updated }` |\n| `issue schema` | `--example-only` | `{ schema, example }` for `--input-file`, or just the example; needs no connection |\n| `issue transition` \u270E | `<key> --transition <name-or-id>` or `--to <intent-or-status>` | `{ transitioned, transition }`; with `--to`, `meta.transition` says what it resolved to |\n| `issue transitions` | `<key>` | Transitions available now |\n| `issue comment` \u270E | `<key> --body` | The comment, plus `bodyText` |\n| `issue comments` | `<key> --limit --cursor` | Every comment, or a page of them, each with `bodyText` |\n| `issue log-work` \u270E | `<key> --time-spent --started --comment` | The worklog, plus `commentText` |\n| `issue label` \u270E | `<key> --labels` | `{ updated, labelsAdded }` |\n| `issue unlabel` \u270E | `<key> --labels` | `{ updated, labelsRemoved }` |\n| `issue assign` \u270E | `<key> --assignee <account-id>` | `{ assigned, assignee }` |\n| `issue link` \u270E | `<key> --target --type` | `{ linked, to, type }` |\n| `issue search` | `--jql` or `--jql-file`, `--limit --cursor --updated-since --fields` | `{ issues, maxResults, isLast }` |\n| `issue fields` | `--discover --custom-only --project --issue-type` | Registered custom fields, or Jira\'s field list with `suggestedType` (and `allowedValues` with `--project`) |\n| `issue attach` \u270E | `<key> --file` | The attachments Jira created |\n| `issue attachments` | `<key>` | The issue\'s attachments |\n| `issue download` | `<key> <attachment-id> --dir` | `{ saved, filename, size }` |\n| `issue set-sprint` \u270E | `<key> --sprint` | `{ updated, sprint }` |\n| `project list` | `--query --limit --cursor` | Every visible project, or a page of them |\n| `project get` | `<project>` | The project |\n| `user search` | `--query --limit --cursor` | One page of matching users, with `accountId` |\n| `board list` | `--project --limit --cursor` | Agile boards |\n| `sprint list` | `--board` or `--project`, `--state`, `--limit --cursor` (with `--board`) | Sprints, each once |\n\n```bash\ntoil jira-cloud issue search --jql \'project = PROJ AND status = "In Progress"\' --limit 20\ntoil jira-cloud user search --query smith\ntoil jira-cloud issue create --project PROJ --type Bug --summary "Login broken" --description "Open the login page in Safari; the button does nothing." --assignee 5b10ac8d82e05b22cc7d4ef5 --allow-write\ntoil jira-cloud issue log-work PROJ-123 --time-spent "2h 30m" --started 2026-01-15T09:00:00.000+0000 --allow-write\ntoil jira-cloud issue link PROJ-123 --target PROJ-456 --type Blocks --allow-write\ntoil jira-cloud project get PROJ\ntoil jira-cloud sprint list --project PROJ --state active\n```\n\n### People are accountIds\n\n`--assignee` takes an **accountId** (`5b10ac8d82e05b22cc7d4ef5`), never a username or\nemail: Jira Cloud has no usernames in its API. Find one with `user search --query\n<name or email>`. People in output (`assignee`, `reporter`, `author`) carry\n`accountId` and `displayName`; an email address appears only where the person\'s\nprofile settings allow it. A `user`-typed custom field sends `{ "accountId": ... }`.\n\n### Rich text (ADF)\n\nA description, a comment body and a worklog comment are ADF documents on Jira Cloud.\ntoil converts them simply, and no more:\n\n- **In** (`--description`, `--body`, `--comment`): plain text. A blank line starts a\n new paragraph; a single line break becomes a hard break. Markdown, wiki markup and\n HTML are **not** interpreted: `**bold**` arrives as those characters. A line break\n has to be a real one: in bash, `$\'one\\ntwo\'`; `\\n` inside ordinary quotes is two\n characters.\n- **In, from `--input-file`**: `fields.description` may also be an ADF document\n object (`{ "type": "doc", ... }`), sent as it is, for formatting plain text can\'t\n carry.\n- **Out**: Jira\'s ADF is returned untouched (`fields.description`, `body`,\n `comment`), and a plain-text rendering sits beside it: `descriptionText` on an issue\n (`null` when it has no description), `bodyText` on each comment and `commentText` on\n a worklog. Formatting is dropped; text, mentions, emoji, links, dates, list items\n (`- `, `1. `) and table cells (`a | b`) keep their words.\n\n### Search\n\n`issue search` uses Jira Cloud\'s enhanced JQL search, which pages by token and reports\n**no total**. Without `--limit` it reads every match. With `--limit N`\nit returns at most N, `isLast` says whether that was all, and `meta.page.nextCursor`\nresumes it: pass it back as `--cursor` with `--limit`. `maxResults` in `data`\nis how many issues came back. `--fields` takes field ids or registered names; the\ndefault is summary, status, priority, assignee, issuetype, project, created, updated,\nlabels, reporter and every registered custom field. `--start-at` from `jira` doesn\'t\nexist here, since the API has no offsets.\n\n### Paging, changes since, history and several issues\n\nThese are what a sync needs: read everything once, then only what changed.\n\n```bash\ntoil jira-cloud issue search --jql \'project = ABC\' --limit 100\ntoil jira-cloud issue search --jql \'project = ABC ORDER BY updated\' --updated-since 2026-10-01T09:30:00Z\ntoil jira-cloud issue history ABC-123\ntoil jira-cloud issue get ABC-1 ABC-2 ABC-7\ntoil jira-cloud project list --limit 50\n```\n\n- **Paging.** Every list and search pages the same way. Without `--limit`,\n a list returns every item (`user search` excepted, below). With one, it returns that many and `meta.page.nextCursor` says where the next page\n starts; pass it back as `--cursor`, unchanged. `null` means that was the last page.\n `user search` is always one page; a full page hands out a cursor, which may lead\n to an empty one. `issue transitions`, `issue attachments` and `issue fields` have no\n paging, because Jira sends each of them whole. `sprint list` pages only with\n `--board`, since `--project` gathers sprints from several boards.\n- **`--updated-since <iso>`** on `issue search` adds `updated >= "<instant>"` to the JQL,\n before any `ORDER BY`, with your JQL in parentheses. The instant is an ISO 8601\n date (`2026-10-01`, read as midnight UTC) or a date and time with a zone\n (`2026-10-01T09:30:00Z`). JQL has no time zones, so toil reads your account\'s zone\n from `/rest/api/3/myself` and writes the instant in it, rounded down to the minute;\n an issue near the boundary can come back twice, never not at all. If Jira names no\n zone it knows, toil writes UTC and warns with `JIRA_CLOUD_TIME_ZONE`. On its own,\n `--updated-since` is the whole query.\n- **`issue history`** reads `/rest/api/3/issue/{key}/changelog`, oldest first, each\n entry with `id`, `author` (an `accountId`), `created` and `items` (`field`,\n `fieldtype`, `fieldId`, `from`, `fromString`, `to`, `toString`).\n- **Several issues.** Give `issue get` several keys (up to 100) and it reads them in one\n `POST /rest/api/3/issue/bulkfetch` and returns `{ issues, errors }`: the issues in\n the order you asked, and each key that couldn\'t be read as `{ key, code, message }`,\n with a `JIRA_CLOUD_BULK_PARTIAL` warning, and never more than one error per key.\n Jira leaves out a key it can\'t find or won\'t show, returns a moved issue under its\n new key, and names an issue it couldn\'t fetch only by id. A key asked for by id\n that Jira couldn\'t fetch is `HTTP` with Jira\'s message. A key with no answer is\n `NOT_FOUND` when everything else Jira sent is accounted for; otherwise it\'s\n `UNMATCHED`, with a message naming the issues returned under other keys and the\n ids Jira couldn\'t fetch, since the answer doesn\'t say which is which. Issues\n returned under another key still come back, after the others. One key returns\n the issue itself. Over MCP, `key` takes a string or a list.\n\n## Large fields via --input-file\n\n`issue create` and `issue update` take `--input-file <path>` (`-` reads stdin on the\nCLI) describing the issue as `{ project, issueType, fields: { ... } }`.\n`toil jira-cloud issue schema` returns its JSON Schema and an example. Any string value in\n`fields` may be `@path/to/file` to read it from a file. Flags override matching keys\nfrom the file, and each override is reported in `meta.warnings` as\n`JIRA_CLOUD_INPUT_OVERRIDDEN`. The project comes from `--project`, then the file, then\nthe connection\'s `project`; `meta.context` says which.\n\n```bash\ntoil jira-cloud issue schema --example-only > envelope.json # the example is in .data\ntoil jira-cloud issue create --input-file issue.json --priority Low --allow-write\n```\n\nOver MCP, `-` is refused because stdin carries the protocol; pass a file path.\n\n## Custom fields\n\n`--field Name=value` (repeatable), `--fields-file` and `--input-file` accept a raw field\nid (`customfield_10016`) or a standard field name (`fixVersions`) with no setup, and\nsend the value as given. `Name=@file.json` reads the value from a file: JSON when it\nparses, text otherwise.\n\nTo use a **friendly name** in flags, JQL and output, register the field on the\nconnection:\n\n```json\n"customFields": [{ "id": "customfield_10016", "name": "Story Points", "type": "number" }]\n```\n\n`type` shapes a `--field` value: `string`, `number`, `date`, `datetime`, `select`\n(`{value}`), `multi-select`, `option-id` (`{id}`), `cascading-select` (`parentId` or\n`parentId:childId`), `user` (`{accountId}`), `multi-user` (comma-separated accountIds, `[{accountId}]`), `labels`, `url`, and `textarea`, which\nis plain text sent as ADF, since a multi-line text field takes ADF on Cloud. Omit it to\nsend the raw string. A value in `--fields-file` or `--input-file` is sent untouched, so\na multi-line text field there needs ADF. `issue fields --discover` lists Jira\'s fields with a\n`suggestedType` (a single-line text field is `string`, a multi-line one `textarea`); add\n`--project PROJ` for each select field\'s `allowedValues`, from the paged createmeta\nendpoints. **Sprint is not a custom field**: use `issue set-sprint` after the issue exists.\n\n## Attachments\n\n`issue attach` uploads one file as multipart with `X-Atlassian-Token: no-check`.\n`issue download` looks the id up on the issue, then asks Jira for the bytes with\n`GET /rest/api/3/attachment/content/<id>?redirect=false`, so the request never leaves\nyour site and the credential goes nowhere else. It saves under `.toil/` (or `--dir`),\nkeeping only the file name, and never replaces a file that\'s already there. A name\nWindows would read as another file is saved as one it won\'t: a device name such as\n`CON` gets a leading `_`, a `:` and what follows it is dropped, as are trailing dots\nand spaces.\n\n## Notes\n\n- `issue create` doesn\'t check for duplicates. After a timeout, search for the summary\n before retrying: the issue may already exist.\n- `issue update` with nothing to change is `INVALID_INPUT`; nothing is sent.\n- `issue log-work` needs `--started`: Jira Cloud\'s API requires it, where `jira` lets the\n server default it.\n- `sprint list --project` reads scrum and team-managed (`simple`) boards and skips\n kanban ones. A team-managed board whose project hasn\'t turned sprints on answers 400;\n it\'s skipped with a `JIRA_CLOUD_NO_SPRINTS` warning naming it. Any other failure is\n the command\'s error.\n- `issue transition` and `issue link` treat an all-digits value as an id and anything\n else as a name (case-insensitive), looked up first.\n- An issue key or id is sent as one URL path segment, encoded, so it can\'t change the\n endpoint called. A project key from `--project`, the connection\'s `project` setting\n or a dossier that holds `/`, `\\`, `?`, `#`, `%` or a control character is refused\n with `INVALID_INPUT`.\n- A 429 is retried after the delay Jira asks for, as in every area.\n\n## Checking a dossier\n\n`check-dossier` checks the call\'s dossier: each project key it names (`project`, `projects`) exists, and each field alias in `fields` names a field id the site has. It\'s `toil jira-cloud check-dossier` (`--dossier <name|file>`, or the dossier the folder resolves to), and it returns `{ dossier, connection, env, ok, checked, checks, unchecked }`, one check per value with its key path. The CLI exits 1 when one is missing. A failure other than not-found (a bad token, an unreachable host) fails the command. Read only.\n',
140338
- "jira.md": '---\narea: jira\ndescription: Issues, JQL search, transitions, comments, worklogs, labels, links, attachments, custom fields, boards and sprints on Jira Data Center\n---\n\n# Jira Data Center (`jira`)\n\nIssues, JQL search, transitions, comments, worklogs, labels, links, attachments,\ncustom fields, boards and sprints on **Jira Data Center / Server** (`/rest/api/2`\nand `/rest/agile/1.0`). Verification level: `unit`.\n\n**Supported versions:** Jira Data Center 8.14 or later (REST API 2 and Agile REST API 1.0). toil\nauthenticates with a personal access token, which Jira Data Center added in 8.14. No\nrelease has been verified yet.\n\n## Credential\n\nA Jira **personal access token**: in Jira, your profile picture \u2192 Profile \u2192\nPersonal Access Tokens \u2192 Create token. toil sends it as `Authorization: Bearer <token>`.\nThere is no username, password or browser login.\n\n## Configuration\n\n| Key | Env var | Required | Meaning |\n|-----|---------|----------|---------|\n| `baseUrl` | `TOIL_JIRA_BASE_URL` | yes | Jira server root, e.g. `https://jira.imagile.dev` (keep any context path, e.g. `https://jira.imagile.dev/jira`) |\n| `apiToken` | `TOIL_JIRA_API_TOKEN` | yes | Personal access token |\n| `customFields` | `TOIL_JIRA_CUSTOM_FIELDS` (JSON) | no | Custom fields addressable by friendly name; see **Custom fields** |\n| `project` | `TOIL_JIRA_PROJECT` | no | Default project for `issue create` |\n| `issueType` | `TOIL_JIRA_ISSUE_TYPE` | no | Default issue type for `issue create` (`Task` when unset) |\n| `priority` | `TOIL_JIRA_PRIORITY` | no | Default priority for `issue create` |\n| `writes` | `TOIL_JIRA_WRITES` | no | `true` lets write commands run (with `--allow-write`) |\n\nEnvironment variables (CI, or a one-off shell):\n\n```bash\nexport TOIL_JIRA_BASE_URL=https://jira.imagile.dev\nexport TOIL_JIRA_API_TOKEN=<your personal access token>\n```\n\nOr `~/.toil/config.json`, with `project`, `issueType` and `priority` usually set once\nunder `defaults.jira` so every Jira connection shares them:\n\n```json\n{\n "version": 2,\n "connections": {\n "corp-jira": { "area": "jira", "baseUrl": "https://jira.imagile.dev", "writes": true }\n },\n "defaults": { "jira": { "connection": "corp-jira", "project": "ABC", "issueType": "Story" } }\n}\n```\n\nThe token never goes in this file; a plaintext one there is refused with\n`CONFIG_INVALID`. Run `toil connections add corp-jira --area jira` (or\n`toil connections login corp-jira` for an existing connection) to keep it in the OS\ncredential store, which writes `"apiToken": "keychain:\u2026"`, or set\n`TOIL_JIRA_API_TOKEN`.\n\nEnv vars always win over the file. A second Jira server is a second connection\n(`"lab-jira": { "area": "jira", ... }`), chosen per call with `--connection lab-jira`\nor configured from env with `TOIL_CONN_LAB_JIRA_AREA=jira` plus\n`TOIL_CONN_LAB_JIRA_BASE_URL` and `TOIL_CONN_LAB_JIRA_API_TOKEN`.\n\n## Commands\n\nEvery command also takes `--connection <name>`. Write commands (marked \u270E) need\n`writes: true` on the connection **and** `--allow-write`; over MCP they are only\nlisted when writes are on, and `allowWrite: true` stands in for the flag.\n\n| Command | Arguments and flags | Returns |\n|---------|-------|---------|\n| `issue get` | `<key...>` (up to 100) | The issue; registered custom fields under their friendly names. With several keys, `{ issues, errors }` |\n| `issue history` | `<key> --limit --cursor` | The issue\'s change history: `id`, `author`, `created`, `items` |\n| `issue create` \u270E | `--project --type --summary --description --priority --assignee --labels --parent --field (repeatable) --fields-file --input-file` | The created issue, read back |\n| `issue update` \u270E | `<key> --summary --description --priority --assignee --labels --field --fields-file --input-file` | `{ updated }` |\n| `issue schema` | `--example-only` | `{ schema, example }` for `--input-file`, or just the example |\n| `issue transition` \u270E | `<key> --transition <name-or-id>` or `--to <intent-or-status>` | `{ transitioned, transition }`; with `--to`, `meta.transition` says what it resolved to |\n| `issue transitions` | `<key>` | Transitions available now |\n| `issue comment` \u270E | `<key> --body` | The comment |\n| `issue comments` | `<key> --limit --cursor` | Every comment, or a page of them |\n| `issue log-work` \u270E | `<key> --time-spent --comment --started` | The worklog |\n| `issue search` | `--jql` or `--jql-file`, `--limit --start-at --cursor --updated-since --fields` | `{ issues, total, startAt, maxResults }` |\n| `issue label` \u270E / `issue unlabel` \u270E | `<key> --labels a,b` | `{ updated, labelsAdded }` / `{ updated, labelsRemoved }` |\n| `issue assign` \u270E | `<key> --assignee <username>` | `{ assigned, assignee }` |\n| `issue link` \u270E | `<key> --target --type` | `{ linked, to, type }` |\n| `issue attach` \u270E | `<key> --file` | The attachments created |\n| `issue attachments` | `<key>` | Attachments (id, filename, size, mimeType, content) |\n| `issue download` | `<key> <attachment-id> --dir` | `{ saved, filename, size }`; saves to `.toil/` by default |\n| `issue fields` | `--discover --custom-only --project --issue-type` | Registered fields, or Jira\'s field list with `suggestedType` and `allowedValues` |\n| `issue set-sprint` \u270E | `<key> --sprint <id>` | `{ updated, sprint }` |\n| `board list` | `--project --limit --cursor` | Boards (id, name, scrum or kanban) |\n| `sprint list` | `--board` or `--project`, `--state active,future,closed`, `--limit --cursor` (with `--board`) | Sprints with dates and goal |\n| `api` | `<method> <path> --query key=value (repeatable) --body-file --content-type` | The response body; see **Any endpoint** below. \u270E for `POST`, `PUT`, `PATCH`, `DELETE` |\n| `check-dossier` | `--dossier <name\\|file>` (or the folder\'s dossier) | `{ dossier, connection, env, ok, checked, checks, unchecked }`: each project and field id the dossier names, found or not; exit 1 when one is missing |\n\nOver MCP the same commands are tools named after the path, with spaces and\nhyphens as underscores (`jira_issue_get`, `jira_sprint_list`,\n`jira_issue_log_work`), taking camelCase fields named after the arguments and\nflags (`key`, `issueType`, `limit`, `attachmentId`).\n\n## Examples\n\n```bash\ntoil jira issue get ABC-123\ntoil jira issue search --jql \'project = ABC AND status = "In Progress"\' --limit 20\ntoil jira issue search --jql-file query.jql --fields summary,status,"Story Points"\ntoil jira issue create --project ABC --type Bug --summary "Login broken on Safari" --priority High --allow-write\ntoil jira issue transition ABC-123 --transition "In Progress" --allow-write\ntoil jira issue transition ABC-123 --to review --allow-write\ntoil jira issue comment ABC-123 --body "Reproduced on staging." --allow-write\ntoil jira issue log-work ABC-123 --time-spent "2h 30m" --comment "Investigated the failing build" --allow-write\ntoil jira issue link ABC-123 --target ABC-456 --type Blocks --allow-write\ntoil jira sprint list --project ABC --state active,future\ntoil jira issue set-sprint ABC-123 --sprint 42 --allow-write\ntoil jira issue download ABC-123 10001 --dir downloads\n```\n\n`issue search` without `--limit` pages through every match, so bound broad\nqueries. `meta.page.nextCursor` is the `--start-at` for the next page (or `null`).\n\n## Paging, changes since, history and several issues\n\nThese are what a sync needs: read everything once, then only what changed.\n\n```bash\ntoil jira issue search --jql \'project = ABC\' --limit 100\ntoil jira issue search --jql \'project = ABC\' --limit 100 --cursor 100\ntoil jira issue search --jql \'project = ABC ORDER BY updated\' --updated-since 2026-10-01T09:30:00Z\ntoil jira issue history ABC-123\ntoil jira issue get ABC-1 ABC-2 ABC-7\ntoil jira issue comments ABC-123 --limit 50\n```\n\n- **Paging.** Every list and search pages the same way. Without `--limit`, it\n returns every item. With one, it returns that many and `meta.page.nextCursor`\n says where the next page starts; pass it back as `--cursor`, unchanged. `null`\n means that was the last page. `issue transitions`, `issue attachments` and\n `issue fields` have no paging, because Jira sends each of them whole.\n `sprint list` pages only with `--board`, since `--project` gathers sprints\n from several boards.\n- **`--updated-since <iso>`** on `issue search` adds `updated >= "<instant>"` to the JQL,\n before any `ORDER BY`, with your JQL in parentheses. The instant is an ISO 8601\n date (`2026-10-01`, read as midnight UTC) or a date and time with a zone\n (`2026-10-01T09:30:00Z`). JQL has no time zones, so toil reads your profile\'s\n zone from `/rest/api/2/myself` and writes the instant in it, rounded down to the\n minute; an issue near the boundary can come back twice, never not at all. If Jira\n names no zone it knows, toil writes UTC and warns with `JIRA_TIME_ZONE`. On its\n own, `--updated-since` is the whole query.\n- **`issue history`** returns the history entries Jira records for an issue, each\n with `id`, `author`, `created` and `items` (`field`, `fieldtype`, `from`,\n `fromString`, `to`, `toString`). Data Center sends the history with the issue\n (`expand=changelog`), all at once, and `--limit` / `--cursor` page it. If Jira\n reports more entries than it sent, a `JIRA_CHANGELOG_TRUNCATED` warning says so.\n- **Several issues.** Give `issue get` several keys (up to 100) and it returns\n `{ issues, errors }`: the issues in the order you asked, and each key that couldn\'t\n be read as `{ key, code, message }` (`NOT_FOUND`, or `HTTP` for another refusal),\n with a `JIRA_BULK_PARTIAL` warning. A rejected token or a network failure fails the\n whole call. Data Center has no bulk endpoint, so toil sends one request per key,\n five at a time. One key returns the issue itself. Over MCP, `key`\n takes a string or a list.\n`issue create` takes its project from `--project`, then `project` in `--input-file`, then\nthe connection\'s `project`, and `meta.context.inputs.project` says which: `input` for\nthe flag or the file, `connection` for the setting (`TOIL_JIRA_PROJECT` and\n`defaults.jira.project` both report `connection`, not `default`). The `--project` on `issue fields`,\n`board list` and `sprint list` never falls back to the connection.\n`--time-spent` takes Jira durations (`1d`, `2h 30m`); `--started` takes Jira\'s datetime\nformat (`2024-01-15T09:00:00.000+0000`) and defaults to now.\n\n## Any endpoint: `jira api`\n\nWhen no command above covers an endpoint, `jira api` calls it directly. It sends\nthe connection\'s own credential, the same way every other `jira` command does,\nto a path under the connection\'s `baseUrl`:\n\n```bash\ntoil jira api GET /rest/api/2/myself\ntoil jira api GET /rest/api/2/issue/ABC-123/remotelink\ntoil jira api GET /rest/agile/1.0/board/12/backlog --query fields=summary --query maxResults=20\ntoil jira api POST /rest/api/2/version --body-file version.json --allow-write\ntoil jira api PUT /rest/api/2/issue/ABC-123/watchers --body-file user.json --content-type application/json --allow-write\n```\n\n- **The path** is relative to `baseUrl` (a context path such as `/jira` is kept),\n with or without a leading `/` (in Git Bash on Windows, leave it off: the shell\n rewrites `/rest/...` into a file path, which is refused). A full URL, a scheme, `//host`, a leading\n backslash or a `.` / `..` segment is refused with `INVALID_INPUT` before anything\n is sent, so the token never leaves the connection\'s host.\n- **The method decides the gate.** `GET` and `HEAD` are reads. `POST`, `PUT`,\n `PATCH` and `DELETE` are writes: they need `writes: true` on the connection\n **and** `--allow-write`. `DELETE` works only on the CLI: over MCP, `jira_api`\n refuses it with `INVALID_INPUT`.\n- **`--query key=value`** adds a query parameter; repeat it for more, or to repeat\n a key. **`--body-file <path>`** sends that file (inside the workspace, or `-` for\n stdin) as the body, as `application/json` unless `--content-type` says\n otherwise.\n- **Output:** a JSON body is `data`, parsed. A text body (`text/*`, XML, or no content\n type) is `data` as text. Any other body is binary: `data` is its bytes as base64,\n with an `API_BINARY` warning (use `issue download` to save an attachment).\n Text and binary are capped at 1 MB, with an `API_TRUNCATED` warning when the body\n was longer. An empty body (a `204`,\n a `HEAD`) is `null`. `meta.response` is `{ status, contentType }`. Errors use the\n usual codes (`AUTH`, `NOT_FOUND`, `HTTP`, `NETWORK`) with Jira\'s own message. A\n body labelled JSON that doesn\'t parse comes back as text, with an `API_NOT_JSON`\n warning.\n- **Over MCP** it\'s the `jira_api` tool, with `method`, `path`, `query` (an array of\n `key=value` strings), `bodyFile`, `contentType` and `allowWrite`.\n\nPrefer a wrapped command when one exists: it knows the endpoint\'s paging, custom\nfields and quirks, and `jira api` doesn\'t.\n\n## Large fields via --input-file\n\n`issue create` and `issue update` take `--input-file <path>` (`-` reads stdin on the\nCLI) describing the issue as `{ project, issueType, fields: { ... } }`.\n`toil jira issue schema` returns its JSON Schema and an example. Any string value in `fields`\nmay be `@path/to/file` to read it from a file. Flags override matching keys from the file,\nand each override is reported in `meta.warnings`.\n\n```bash\ntoil jira issue schema --example-only > envelope.json # the example is in .data\ntoil jira issue create --input-file issue.json --priority Low --allow-write\n```\n\nOver MCP, `-` is refused because stdin carries the protocol; pass a file path.\nRelative paths resolve against the directory toil runs in.\n\n## Custom fields\n\n`--field Name=value` (repeatable), `--fields-file` and `--input-file` accept a raw field\nid (`customfield_10032`) or a standard field name (`fixVersions`) with no setup.\n`Name=@file.json` reads the value from a file: JSON when it parses, text otherwise, which\nalso avoids shell quoting trouble in PowerShell.\n\nTo use a **friendly name** in flags, JQL and output, register the field on the\nconnection:\n\n```json\n"customFields": [{ "id": "customfield_10016", "name": "Story Points", "type": "number" }]\n```\n\n`type` shapes a `--field` value: `string`, `number`, `date`, `datetime`, `select`\n(`{value}`), `multi-select`, `option-id` (`{id}`), `cascading-select` (`parent` or\n`parent:child` ids), `user` (`{name}`), `labels`, `url`, `textarea`. Omit it to send the\nraw string. `toil jira issue fields --discover` lists Jira\'s fields with a `suggestedType`; add\n`--project ABC` to see each select field\'s `allowedValues`. A select field that only\naccepts option ids needs `"type": "option-id"`. **Sprint is not a custom field**: use\n`issue set-sprint` after the issue exists.\n\nA **dossier** can name fields too (`"jira": { "fields": { "storyPoints": "customfield_10016" } }`,\nor `toil dossiers field <dossier> jira storyPoints customfield_10016`). Then\n`issue create` and `issue update` take `--field storyPoints=5` in any folder the dossier\napplies to. An alias takes the type the connection registers for that id. A name the\nconnection already uses keeps the connection\'s meaning.\n\n## Data Center, not Cloud\n\nThis area targets Jira Data Center and Server. Users are **usernames** (`--assignee\njsmith`, `user`-typed fields send `{ "name": ... }`), where Jira Cloud needs an\n`accountId`. Jira Cloud is a separate area, `jira-cloud`, with its own\n`TOIL_JIRA_CLOUD_*` settings; don\'t point this one at a Cloud site.\n\n## Notes\n\n- `issue create` doesn\'t check for duplicates. After a timeout, search for the summary\n before retrying: the issue may already exist.\n- `issue update` with nothing to change still sends an empty update and reports\n `{ updated }`.\n- `issue download` never replaces a file. If one of the same name is already in the target directory, it fails with `INVALID_INPUT`; delete the file or pass a different `--dir`.\n- `issue download` saves a name Windows would read as another file under one it won\'t: a device name such as `CON` or `nul.txt` gets a leading `_`, a `:` and what follows it is dropped, as are trailing dots and spaces, and the characters Windows forbids become `_`. `filename` is still the name Jira gave; `saved` is where the file went. The same holds on every platform.\n- `issue download` only ever sends the token to `baseUrl`\'s host. If Jira names\n another host for the file, toil fetches the same path from `baseUrl` and warns.\n- Issue keys and ids are sent as one URL path segment each, encoded, so a `/` or `?` in\n one can\'t change the endpoint called. A project key from `--project`, the\n connection\'s `project` setting, a dossier or `--input-file` that holds `/`, `\\`, `?`,\n `#`, `%` or a control character is refused with `INVALID_INPUT`.\n',
140440
+ "jira-cloud.md": '---\narea: jira-cloud\ndescription: Issues, JQL search, transitions, comments, worklogs, labels, links, attachments, custom fields, projects, users, boards and sprints on Jira Cloud\n---\n\n# Jira Cloud (`jira-cloud`)\n\nIssues, JQL search, transitions, comments, worklogs, labels, links, attachments,\ncustom fields, projects, users, boards and sprints on **Jira Cloud**\n(`https://<your-site>.atlassian.net`, REST API 3 and the Agile REST API 1.0). Built\nfrom Atlassian\'s API documentation and never run against a live site. Verification\nlevel: `unit`.\n\nFor Jira Data Center or Server, use the `jira` area instead. The two are separate\nareas because their APIs differ: Cloud names people by **accountId**, not username,\nand its rich text is **Atlassian Document Format** (ADF), not a string.\n\n**Supported versions:** The oldest Jira Cloud version toil supports hasn\'t been established. Jira\nCloud is always current. toil calls REST API 3 (`/rest/api/3`, with the enhanced JQL\nsearch at `/rest/api/3/search/jql`) and the Agile REST API 1.0, with an Atlassian\naccount email and API token sent as Basic auth. Nothing has been run against a live\nsite yet.\n\n## Credential\n\nAn **Atlassian account API token** plus that account\'s **email address**. Create\nthe token at https://id.atlassian.com/manage-profile/security/api-tokens (Atlassian\naccount \u2192 Security \u2192 API tokens \u2192 Create API token). toil sends\n`Authorization: Basic base64(<email>:<apiToken>)`, as Atlassian documents for\nscripts. There is no password, OAuth app or browser login. The token acts with the\naccount\'s own permissions, so a read sees what that account can see.\n\nIf the email and token don\'t match, Jira Cloud may treat the call as anonymous\nrather than refuse it: a 401 is `AUTH`, but a missing issue can also surface as\n`NOT_FOUND`, and a search as no results. When a call that should work finds nothing,\ncheck `email` first.\n\n## Configuration\n\n| Key | Env var | Required | Meaning |\n|-----|---------|----------|---------|\n| `baseUrl` | `TOIL_JIRA_CLOUD_BASE_URL` | yes | Jira Cloud site root, `https://<your-site>.atlassian.net` |\n| `email` | `TOIL_JIRA_CLOUD_EMAIL` | yes | Email address of the Atlassian account the token belongs to |\n| `apiToken` | `TOIL_JIRA_CLOUD_API_TOKEN` | yes | Atlassian account API token (a secret) |\n| `customFields` | `TOIL_JIRA_CLOUD_CUSTOM_FIELDS` (JSON) | no | Custom fields addressable by friendly name; see **Custom fields** |\n| `project` | `TOIL_JIRA_CLOUD_PROJECT` | no | Default project for `issue create` |\n| `issueType` | `TOIL_JIRA_CLOUD_ISSUE_TYPE` | no | Default issue type for `issue create` (`Task` when unset) |\n| `priority` | `TOIL_JIRA_CLOUD_PRIORITY` | no | Default priority for `issue create` |\n| `writes` | `TOIL_JIRA_CLOUD_WRITES` | no | `true` lets write commands run (with `--allow-write`) |\n\nThere is no CI fallback variable. The examples use the placeholder\n`https://jira-cloud.imagile.dev`, which never resolves; your own site is\n`https://<your-site>.atlassian.net`.\n\n```bash\nexport TOIL_JIRA_CLOUD_BASE_URL=https://jira-cloud.imagile.dev\nexport TOIL_JIRA_CLOUD_EMAIL=you@example.com\nexport TOIL_JIRA_CLOUD_API_TOKEN=<your API token>\n```\n\nOr `~/.toil/config.json`, with `project`, `issueType` and `priority` usually set once\nunder `defaults.jira-cloud`:\n\n```json\n{\n "version": 2,\n "connections": {\n "imagile-cloud": { "area": "jira-cloud", "baseUrl": "https://jira-cloud.imagile.dev", "email": "you@example.com", "writes": true }\n },\n "defaults": { "jira-cloud": { "connection": "imagile-cloud", "project": "PROJ" } }\n}\n```\n\nThe token never goes in this file; a plaintext one there is refused with\n`CONFIG_INVALID`. Run `toil connections add imagile-cloud --area jira-cloud` (or\n`toil connections login imagile-cloud`) to keep it in the OS credential store, or set\n`TOIL_JIRA_CLOUD_API_TOKEN`. Env vars always win over the file.\n\n## Commands\n\nEvery command also takes `--connection <name>`. Write commands (marked \u270E) need\n`writes: true` on the connection **and** `--allow-write`. Names and flags match\n`jira` wherever the operation is the same. MCP tools are named after the path, with\nspaces and hyphens as underscores (`jira_cloud_issue_get`, `jira_cloud_user_search`).\n\n| Command | Arguments and flags | Returns |\n|---------|-------|---------|\n| `issue get` | `<key...>` (up to 100) | The issue as Jira returns it, registered custom fields under their friendly names, plus `descriptionText`. With several keys, `{ issues, errors }` |\n| `issue history` | `<key> --limit --cursor` | The issue\'s change history, oldest first: `id`, `author`, `created`, `items` |\n| `issue create` \u270E | `--project --type --summary --description --priority --assignee <account-id> --labels --parent --field (repeatable) --fields-file --input-file` | The created issue, read back, plus `descriptionText` |\n| `issue update` \u270E | `<key> --summary --description --priority --assignee <account-id> --labels --field --fields-file --input-file` | `{ updated }` |\n| `issue schema` | `--example-only` | `{ schema, example }` for `--input-file`, or just the example; needs no connection |\n| `issue transition` \u270E | `<key> --transition <name-or-id>` or `--to <intent-or-status>` | `{ transitioned, transition }`; with `--to`, `meta.transition` says what it resolved to |\n| `issue transitions` | `<key>` | Transitions available now |\n| `issue comment` \u270E | `<key> --body` | The comment, plus `bodyText` |\n| `issue comments` | `<key> --limit --cursor` | Every comment, or a page of them, each with `bodyText` |\n| `issue log-work` \u270E | `<key> --time-spent --started --comment` | The worklog, plus `commentText` |\n| `issue label` \u270E | `<key> --labels` | `{ updated, labelsAdded }` |\n| `issue unlabel` \u270E | `<key> --labels` | `{ updated, labelsRemoved }` |\n| `issue assign` \u270E | `<key> --assignee <account-id>` | `{ assigned, assignee }` |\n| `issue link` \u270E | `<key> --target --type` | `{ linked, to, type }` |\n| `issue search` | `--jql` or `--jql-file`, `--limit --cursor --updated-since --fields` | `{ issues, maxResults, isLast }` |\n| `issue fields` | `--discover --custom-only --project --issue-type` | Registered custom fields, or Jira\'s field list with `suggestedType` (and `allowedValues` with `--project`) |\n| `issue attach` \u270E | `<key> --file` | The attachments Jira created |\n| `issue attachments` | `<key>` | The issue\'s attachments |\n| `issue download` | `<key> <attachment-id> --dir` | `{ saved, filename, size }` |\n| `issue set-sprint` \u270E | `<key> --sprint` | `{ updated, sprint }` |\n| `project list` | `--query --limit --cursor` | Every visible project, or a page of them |\n| `project get` | `<project>` | The project |\n| `user search` | `--query --limit --cursor` | One page of matching users, with `accountId` |\n| `board list` | `--project --limit --cursor` | Agile boards |\n| `sprint list` | `--board` or `--project`, `--state`, `--limit --cursor` (with `--board`) | Sprints, each once |\n\n```bash\ntoil jira-cloud issue search --jql \'project = PROJ AND status = "In Progress"\' --limit 20\ntoil jira-cloud user search --query smith\ntoil jira-cloud issue create --project PROJ --type Bug --summary "Login broken" --description "Open the login page in Safari; the button does nothing." --assignee 5b10ac8d82e05b22cc7d4ef5 --allow-write\ntoil jira-cloud issue log-work PROJ-123 --time-spent "2h 30m" --started 2026-01-15T09:00:00.000+0000 --allow-write\ntoil jira-cloud issue link PROJ-123 --target PROJ-456 --type Blocks --allow-write\ntoil jira-cloud project get PROJ\ntoil jira-cloud sprint list --project PROJ --state active\n```\n\n### People are accountIds\n\n`--assignee` takes an **accountId** (`5b10ac8d82e05b22cc7d4ef5`), never a username or\nemail: Jira Cloud has no usernames in its API. Find one with `user search --query\n<name or email>`. People in output (`assignee`, `reporter`, `author`) carry\n`accountId` and `displayName`; an email address appears only where the person\'s\nprofile settings allow it. A `user`-typed custom field sends `{ "accountId": ... }`.\n\n### Rich text (ADF)\n\nA description, a comment body and a worklog comment are ADF documents on Jira Cloud.\ntoil converts them simply, and no more:\n\n- **In** (`--description`, `--body`, `--comment`): plain text. A blank line starts a\n new paragraph; a single line break becomes a hard break. Markdown, wiki markup and\n HTML are **not** interpreted: `**bold**` arrives as those characters. A line break\n has to be a real one: in bash, `$\'one\\ntwo\'`; `\\n` inside ordinary quotes is two\n characters.\n- **In, from `--input-file`**: `fields.description` may also be an ADF document\n object (`{ "type": "doc", ... }`), sent as it is, for formatting plain text can\'t\n carry.\n- **Out**: Jira\'s ADF is returned untouched (`fields.description`, `body`,\n `comment`), and a plain-text rendering sits beside it: `descriptionText` on an issue\n (`null` when it has no description), `bodyText` on each comment and `commentText` on\n a worklog. Formatting is dropped; text, mentions, emoji, links, dates, list items\n (`- `, `1. `) and table cells (`a | b`) keep their words.\n\n### Search\n\n`issue search` uses Jira Cloud\'s enhanced JQL search, which pages by token and reports\n**no total**. Without `--limit` it reads every match. With `--limit N`\nit returns at most N, `isLast` says whether that was all, and `meta.page.nextCursor`\nresumes it: pass it back as `--cursor` with `--limit`. `maxResults` in `data`\nis how many issues came back. `--fields` takes field ids or registered names; the\ndefault is summary, status, priority, assignee, issuetype, project, created, updated,\nlabels, reporter and every registered custom field. `--start-at` from `jira` doesn\'t\nexist here, since the API has no offsets.\n\n### Paging, changes since, history and several issues\n\nThese are what a sync needs: read everything once, then only what changed.\n\n```bash\ntoil jira-cloud issue search --jql \'project = ABC\' --limit 100\ntoil jira-cloud issue search --jql \'project = ABC ORDER BY updated\' --updated-since 2026-10-01T09:30:00Z\ntoil jira-cloud issue history ABC-123\ntoil jira-cloud issue get ABC-1 ABC-2 ABC-7\ntoil jira-cloud project list --limit 50\n```\n\n- **Paging.** Every list and search pages the same way. Without `--limit`,\n a list returns every item (`user search` excepted, below). With one, it returns that many and `meta.page.nextCursor` says where the next page\n starts; pass it back as `--cursor`, unchanged. `null` means that was the last page.\n `user search` is always one page; a full page hands out a cursor, which may lead\n to an empty one. `issue transitions`, `issue attachments` and `issue fields` have no\n paging, because Jira sends each of them whole. `sprint list` pages only with\n `--board`, since `--project` gathers sprints from several boards.\n- **`--updated-since <iso>`** on `issue search` adds `updated >= "<instant>"` to the JQL,\n before any `ORDER BY`, with your JQL in parentheses. The instant is an ISO 8601\n date (`2026-10-01`, read as midnight UTC) or a date and time with a zone\n (`2026-10-01T09:30:00Z`). JQL has no time zones, so toil reads your account\'s zone\n from `/rest/api/3/myself` and writes the instant in it, rounded down to the minute;\n an issue near the boundary can come back twice, never not at all. If Jira names no\n zone it knows, toil writes UTC and warns with `JIRA_CLOUD_TIME_ZONE`. On its own,\n `--updated-since` is the whole query.\n- **`issue history`** reads `/rest/api/3/issue/{key}/changelog`, oldest first, each\n entry with `id`, `author` (an `accountId`), `created` and `items` (`field`,\n `fieldtype`, `fieldId`, `from`, `fromString`, `to`, `toString`).\n- **Several issues.** Give `issue get` several keys (up to 100) and it reads them in one\n `POST /rest/api/3/issue/bulkfetch` and returns `{ issues, errors }`: the issues in\n the order you asked, and each key that couldn\'t be read as `{ key, code, message }`,\n with a `JIRA_CLOUD_BULK_PARTIAL` warning, and never more than one error per key.\n Jira leaves out a key it can\'t find or won\'t show, returns a moved issue under its\n new key, and names an issue it couldn\'t fetch only by id. A key asked for by id\n that Jira couldn\'t fetch is `HTTP` with Jira\'s message. A key with no answer is\n `NOT_FOUND` when everything else Jira sent is accounted for; otherwise it\'s\n `UNMATCHED`, with a message naming the issues returned under other keys and the\n ids Jira couldn\'t fetch, since the answer doesn\'t say which is which. Issues\n returned under another key still come back, after the others. One key returns\n the issue itself. Over MCP, `key` takes a string or a list.\n\n## Large fields via --input-file\n\n`issue create` and `issue update` take `--input-file <path>` (`-` reads stdin on the\nCLI) describing the issue as `{ project, issueType, fields: { ... } }`.\n`toil jira-cloud issue schema` returns its JSON Schema and an example. Any string value in\n`fields` may be `@path/to/file` to read it from a file. Flags override matching keys\nfrom the file, and each override is reported in `meta.warnings` as\n`JIRA_CLOUD_INPUT_OVERRIDDEN`. The project comes from `--project`, then the file, then\nthe connection\'s `project`; `meta.context` says which.\n\n```bash\ntoil jira-cloud issue schema --example-only > envelope.json # the example is in .data\ntoil jira-cloud issue create --input-file issue.json --priority Low --allow-write\n```\n\nOver MCP, `-` is refused because stdin carries the protocol; pass a file path.\n\n## Custom fields\n\n`--field Name=value` (repeatable), `--fields-file` and `--input-file` accept a raw field\nid (`customfield_10016`) or a standard field name (`fixVersions`) with no setup, and\nsend the value as given. `Name=@file.json` reads the value from a file: JSON when it\nparses, text otherwise.\n\nTo use a **friendly name** in flags, JQL and output, register the field on the\nconnection:\n\n```json\n"customFields": [{ "id": "customfield_10016", "name": "Story Points", "type": "number" }]\n```\n\n`type` shapes a `--field` value: `string`, `number`, `date`, `datetime`, `select`\n(`{value}`), `multi-select`, `option-id` (`{id}`), `cascading-select` (`parentId` or\n`parentId:childId`), `user` (`{accountId}`), `multi-user` (comma-separated accountIds, `[{accountId}]`), `labels`, `url`, and `textarea`, which\nis plain text sent as ADF, since a multi-line text field takes ADF on Cloud. Omit it to\nsend the raw string. A value in `--fields-file` or `--input-file` is sent untouched, so\na multi-line text field there needs ADF. `issue fields --discover` lists Jira\'s fields with a\n`suggestedType` (a single-line text field is `string`, a multi-line one `textarea`); add\n`--project PROJ` for each select field\'s `allowedValues`, from the paged createmeta\nendpoints. **Sprint is not a custom field**: use `issue set-sprint` after the issue exists.\n\n## Attachments\n\n`issue attach` uploads one file as multipart with `X-Atlassian-Token: no-check`.\n`issue download` looks the id up on the issue, then asks Jira for the bytes with\n`GET /rest/api/3/attachment/content/<id>?redirect=false`, so the request never leaves\nyour site and the credential goes nowhere else. It saves under `.toil/` (or `--dir`),\nkeeping only the file name, and never replaces a file that\'s already there. A name\nWindows would read as another file is saved as one it won\'t: a device name such as\n`CON` gets a leading `_`, a `:` and what follows it is dropped, as are trailing dots\nand spaces.\n\n## Ticket the work\n\nBefore starting work no ticket covers, rank your open issues against it:\n\n```bash\ntoil jira-cloud issue search --jql "assignee = currentUser() AND statusCategory != Done" --fields summary,description,status,issuetype,labels,parent | toil util owi map | toil util owi similar --query "Card payments time out at checkout"\n```\n\nThen ask the person, as `core.md`, **Ticket the work**, says: attach the work to a\nmatch (nothing is written), create a sub-task under it, or create a new ticket. A\nsub-task is\n`toil jira-cloud issue create --type Subtask --parent PAY-12 --summary "<text>" --allow-write`\n(the project may name the type differently); a new ticket takes the project and type\nfrom the dossier and the connection. Both are writes, made only on the person\'s yes.\n\n## Notes\n\n- `issue create` doesn\'t check for duplicates. After a timeout, search for the summary\n before retrying: the issue may already exist.\n- `issue update` with nothing to change is `INVALID_INPUT`; nothing is sent.\n- `issue log-work` needs `--started`: Jira Cloud\'s API requires it, where `jira` lets the\n server default it.\n- `sprint list --project` reads scrum and team-managed (`simple`) boards and skips\n kanban ones. A team-managed board whose project hasn\'t turned sprints on answers 400;\n it\'s skipped with a `JIRA_CLOUD_NO_SPRINTS` warning naming it. Any other failure is\n the command\'s error.\n- `issue transition` and `issue link` treat an all-digits value as an id and anything\n else as a name (case-insensitive), looked up first.\n- An issue key or id is sent as one URL path segment, encoded, so it can\'t change the\n endpoint called. A project key from `--project`, the connection\'s `project` setting\n or a dossier that holds `/`, `\\`, `?`, `#`, `%` or a control character is refused\n with `INVALID_INPUT`.\n- A 429 is retried after the delay Jira asks for, as in every area.\n\n## Checking a dossier\n\n`check-dossier` checks the call\'s dossier: each project key it names (`project`, `projects`) exists, and each field alias in `fields` names a field id the site has. It\'s `toil jira-cloud check-dossier` (`--dossier <name|file>`, or the dossier the folder resolves to), and it returns `{ dossier, connection, env, ok, checked, checks, unchecked }`, one check per value with its key path. The CLI exits 1 when one is missing. A failure other than not-found (a bad token, an unreachable host) fails the command. Read only.\n',
140441
+ "jira.md": '---\narea: jira\ndescription: Issues, JQL search, transitions, comments, worklogs, labels, links, attachments, custom fields, boards and sprints on Jira Data Center\n---\n\n# Jira Data Center (`jira`)\n\nIssues, JQL search, transitions, comments, worklogs, labels, links, attachments,\ncustom fields, boards and sprints on **Jira Data Center / Server** (`/rest/api/2`\nand `/rest/agile/1.0`). Verification level: `unit`.\n\n**Supported versions:** Jira Data Center 8.14 or later (REST API 2 and Agile REST API 1.0). toil\nauthenticates with a personal access token, which Jira Data Center added in 8.14. No\nrelease has been verified yet.\n\n## Credential\n\nA Jira **personal access token**: in Jira, your profile picture \u2192 Profile \u2192\nPersonal Access Tokens \u2192 Create token. toil sends it as `Authorization: Bearer <token>`.\nThere is no username, password or browser login.\n\n## Configuration\n\n| Key | Env var | Required | Meaning |\n|-----|---------|----------|---------|\n| `baseUrl` | `TOIL_JIRA_BASE_URL` | yes | Jira server root, e.g. `https://jira.imagile.dev` (keep any context path, e.g. `https://jira.imagile.dev/jira`) |\n| `apiToken` | `TOIL_JIRA_API_TOKEN` | yes | Personal access token |\n| `customFields` | `TOIL_JIRA_CUSTOM_FIELDS` (JSON) | no | Custom fields addressable by friendly name; see **Custom fields** |\n| `project` | `TOIL_JIRA_PROJECT` | no | Default project for `issue create` |\n| `issueType` | `TOIL_JIRA_ISSUE_TYPE` | no | Default issue type for `issue create` (`Task` when unset) |\n| `priority` | `TOIL_JIRA_PRIORITY` | no | Default priority for `issue create` |\n| `writes` | `TOIL_JIRA_WRITES` | no | `true` lets write commands run (with `--allow-write`) |\n\nEnvironment variables (CI, or a one-off shell):\n\n```bash\nexport TOIL_JIRA_BASE_URL=https://jira.imagile.dev\nexport TOIL_JIRA_API_TOKEN=<your personal access token>\n```\n\nOr `~/.toil/config.json`, with `project`, `issueType` and `priority` usually set once\nunder `defaults.jira` so every Jira connection shares them:\n\n```json\n{\n "version": 2,\n "connections": {\n "corp-jira": { "area": "jira", "baseUrl": "https://jira.imagile.dev", "writes": true }\n },\n "defaults": { "jira": { "connection": "corp-jira", "project": "ABC", "issueType": "Story" } }\n}\n```\n\nThe token never goes in this file; a plaintext one there is refused with\n`CONFIG_INVALID`. Run `toil connections add corp-jira --area jira` (or\n`toil connections login corp-jira` for an existing connection) to keep it in the OS\ncredential store, which writes `"apiToken": "keychain:\u2026"`, or set\n`TOIL_JIRA_API_TOKEN`.\n\nEnv vars always win over the file. A second Jira server is a second connection\n(`"lab-jira": { "area": "jira", ... }`), chosen per call with `--connection lab-jira`\nor configured from env with `TOIL_CONN_LAB_JIRA_AREA=jira` plus\n`TOIL_CONN_LAB_JIRA_BASE_URL` and `TOIL_CONN_LAB_JIRA_API_TOKEN`.\n\n## Commands\n\nEvery command also takes `--connection <name>`. Write commands (marked \u270E) need\n`writes: true` on the connection **and** `--allow-write`; over MCP they are only\nlisted when writes are on, and `allowWrite: true` stands in for the flag.\n\n| Command | Arguments and flags | Returns |\n|---------|-------|---------|\n| `issue get` | `<key...>` (up to 100) | The issue; registered custom fields under their friendly names. With several keys, `{ issues, errors }` |\n| `issue history` | `<key> --limit --cursor` | The issue\'s change history: `id`, `author`, `created`, `items` |\n| `issue create` \u270E | `--project --type --summary --description --priority --assignee --labels --parent --field (repeatable) --fields-file --input-file` | The created issue, read back |\n| `issue update` \u270E | `<key> --summary --description --priority --assignee --labels --field --fields-file --input-file` | `{ updated }` |\n| `issue schema` | `--example-only` | `{ schema, example }` for `--input-file`, or just the example |\n| `issue transition` \u270E | `<key> --transition <name-or-id>` or `--to <intent-or-status>` | `{ transitioned, transition }`; with `--to`, `meta.transition` says what it resolved to |\n| `issue transitions` | `<key>` | Transitions available now |\n| `issue comment` \u270E | `<key> --body` | The comment |\n| `issue comments` | `<key> --limit --cursor` | Every comment, or a page of them |\n| `issue log-work` \u270E | `<key> --time-spent --comment --started` | The worklog |\n| `issue search` | `--jql` or `--jql-file`, `--limit --start-at --cursor --updated-since --fields` | `{ issues, total, startAt, maxResults }` |\n| `issue label` \u270E / `issue unlabel` \u270E | `<key> --labels a,b` | `{ updated, labelsAdded }` / `{ updated, labelsRemoved }` |\n| `issue assign` \u270E | `<key> --assignee <username>` | `{ assigned, assignee }` |\n| `issue link` \u270E | `<key> --target --type` | `{ linked, to, type }` |\n| `issue attach` \u270E | `<key> --file` | The attachments created |\n| `issue attachments` | `<key>` | Attachments (id, filename, size, mimeType, content) |\n| `issue download` | `<key> <attachment-id> --dir` | `{ saved, filename, size }`; saves to `.toil/` by default |\n| `issue fields` | `--discover --custom-only --project --issue-type` | Registered fields, or Jira\'s field list with `suggestedType` and `allowedValues` |\n| `issue set-sprint` \u270E | `<key> --sprint <id>` | `{ updated, sprint }` |\n| `board list` | `--project --limit --cursor` | Boards (id, name, scrum or kanban) |\n| `sprint list` | `--board` or `--project`, `--state active,future,closed`, `--limit --cursor` (with `--board`) | Sprints with dates and goal |\n| `api` | `<method> <path> --query key=value (repeatable) --body-file --content-type` | The response body; see **Any endpoint** below. \u270E for `POST`, `PUT`, `PATCH`, `DELETE` |\n| `check-dossier` | `--dossier <name\\|file>` (or the folder\'s dossier) | `{ dossier, connection, env, ok, checked, checks, unchecked }`: each project and field id the dossier names, found or not; exit 1 when one is missing |\n\nOver MCP the same commands are tools named after the path, with spaces and\nhyphens as underscores (`jira_issue_get`, `jira_sprint_list`,\n`jira_issue_log_work`), taking camelCase fields named after the arguments and\nflags (`key`, `issueType`, `limit`, `attachmentId`).\n\n## Examples\n\n```bash\ntoil jira issue get ABC-123\ntoil jira issue search --jql \'project = ABC AND status = "In Progress"\' --limit 20\ntoil jira issue search --jql-file query.jql --fields summary,status,"Story Points"\ntoil jira issue create --project ABC --type Bug --summary "Login broken on Safari" --priority High --allow-write\ntoil jira issue transition ABC-123 --transition "In Progress" --allow-write\ntoil jira issue transition ABC-123 --to review --allow-write\ntoil jira issue comment ABC-123 --body "Reproduced on staging." --allow-write\ntoil jira issue log-work ABC-123 --time-spent "2h 30m" --comment "Investigated the failing build" --allow-write\ntoil jira issue link ABC-123 --target ABC-456 --type Blocks --allow-write\ntoil jira sprint list --project ABC --state active,future\ntoil jira issue set-sprint ABC-123 --sprint 42 --allow-write\ntoil jira issue download ABC-123 10001 --dir downloads\n```\n\n`issue search` without `--limit` pages through every match, so bound broad\nqueries. `meta.page.nextCursor` is the `--start-at` for the next page (or `null`).\n\n## Paging, changes since, history and several issues\n\nThese are what a sync needs: read everything once, then only what changed.\n\n```bash\ntoil jira issue search --jql \'project = ABC\' --limit 100\ntoil jira issue search --jql \'project = ABC\' --limit 100 --cursor 100\ntoil jira issue search --jql \'project = ABC ORDER BY updated\' --updated-since 2026-10-01T09:30:00Z\ntoil jira issue history ABC-123\ntoil jira issue get ABC-1 ABC-2 ABC-7\ntoil jira issue comments ABC-123 --limit 50\n```\n\n- **Paging.** Every list and search pages the same way. Without `--limit`, it\n returns every item. With one, it returns that many and `meta.page.nextCursor`\n says where the next page starts; pass it back as `--cursor`, unchanged. `null`\n means that was the last page. `issue transitions`, `issue attachments` and\n `issue fields` have no paging, because Jira sends each of them whole.\n `sprint list` pages only with `--board`, since `--project` gathers sprints\n from several boards.\n- **`--updated-since <iso>`** on `issue search` adds `updated >= "<instant>"` to the JQL,\n before any `ORDER BY`, with your JQL in parentheses. The instant is an ISO 8601\n date (`2026-10-01`, read as midnight UTC) or a date and time with a zone\n (`2026-10-01T09:30:00Z`). JQL has no time zones, so toil reads your profile\'s\n zone from `/rest/api/2/myself` and writes the instant in it, rounded down to the\n minute; an issue near the boundary can come back twice, never not at all. If Jira\n names no zone it knows, toil writes UTC and warns with `JIRA_TIME_ZONE`. On its\n own, `--updated-since` is the whole query.\n- **`issue history`** returns the history entries Jira records for an issue, each\n with `id`, `author`, `created` and `items` (`field`, `fieldtype`, `from`,\n `fromString`, `to`, `toString`). Data Center sends the history with the issue\n (`expand=changelog`), all at once, and `--limit` / `--cursor` page it. If Jira\n reports more entries than it sent, a `JIRA_CHANGELOG_TRUNCATED` warning says so.\n- **Several issues.** Give `issue get` several keys (up to 100) and it returns\n `{ issues, errors }`: the issues in the order you asked, and each key that couldn\'t\n be read as `{ key, code, message }` (`NOT_FOUND`, or `HTTP` for another refusal),\n with a `JIRA_BULK_PARTIAL` warning. A rejected token or a network failure fails the\n whole call. Data Center has no bulk endpoint, so toil sends one request per key,\n five at a time. One key returns the issue itself. Over MCP, `key`\n takes a string or a list.\n`issue create` takes its project from `--project`, then `project` in `--input-file`, then\nthe connection\'s `project`, and `meta.context.inputs.project` says which: `input` for\nthe flag or the file, `connection` for the setting (`TOIL_JIRA_PROJECT` and\n`defaults.jira.project` both report `connection`, not `default`). The `--project` on `issue fields`,\n`board list` and `sprint list` never falls back to the connection.\n`--time-spent` takes Jira durations (`1d`, `2h 30m`); `--started` takes Jira\'s datetime\nformat (`2024-01-15T09:00:00.000+0000`) and defaults to now.\n\n## Any endpoint: `jira api`\n\nWhen no command above covers an endpoint, `jira api` calls it directly. It sends\nthe connection\'s own credential, the same way every other `jira` command does,\nto a path under the connection\'s `baseUrl`:\n\n```bash\ntoil jira api GET /rest/api/2/myself\ntoil jira api GET /rest/api/2/issue/ABC-123/remotelink\ntoil jira api GET /rest/agile/1.0/board/12/backlog --query fields=summary --query maxResults=20\ntoil jira api POST /rest/api/2/version --body-file version.json --allow-write\ntoil jira api PUT /rest/api/2/issue/ABC-123/watchers --body-file user.json --content-type application/json --allow-write\n```\n\n- **The path** is relative to `baseUrl` (a context path such as `/jira` is kept),\n with or without a leading `/` (in Git Bash on Windows, leave it off: the shell\n rewrites `/rest/...` into a file path, which is refused). A full URL, a scheme, `//host`, a leading\n backslash or a `.` / `..` segment is refused with `INVALID_INPUT` before anything\n is sent, so the token never leaves the connection\'s host.\n- **The method decides the gate.** `GET` and `HEAD` are reads. `POST`, `PUT`,\n `PATCH` and `DELETE` are writes: they need `writes: true` on the connection\n **and** `--allow-write`. `DELETE` works only on the CLI: over MCP, `jira_api`\n refuses it with `INVALID_INPUT`.\n- **`--query key=value`** adds a query parameter; repeat it for more, or to repeat\n a key. **`--body-file <path>`** sends that file (inside the workspace, or `-` for\n stdin) as the body, as `application/json` unless `--content-type` says\n otherwise.\n- **Output:** a JSON body is `data`, parsed. A text body (`text/*`, XML, or no content\n type) is `data` as text. Any other body is binary: `data` is its bytes as base64,\n with an `API_BINARY` warning (use `issue download` to save an attachment).\n Text and binary are capped at 1 MB, with an `API_TRUNCATED` warning when the body\n was longer. An empty body (a `204`,\n a `HEAD`) is `null`. `meta.response` is `{ status, contentType }`. Errors use the\n usual codes (`AUTH`, `NOT_FOUND`, `HTTP`, `NETWORK`) with Jira\'s own message. A\n body labelled JSON that doesn\'t parse comes back as text, with an `API_NOT_JSON`\n warning.\n- **Over MCP** it\'s the `jira_api` tool, with `method`, `path`, `query` (an array of\n `key=value` strings), `bodyFile`, `contentType` and `allowWrite`.\n\nPrefer a wrapped command when one exists: it knows the endpoint\'s paging, custom\nfields and quirks, and `jira api` doesn\'t.\n\n## Large fields via --input-file\n\n`issue create` and `issue update` take `--input-file <path>` (`-` reads stdin on the\nCLI) describing the issue as `{ project, issueType, fields: { ... } }`.\n`toil jira issue schema` returns its JSON Schema and an example. Any string value in `fields`\nmay be `@path/to/file` to read it from a file. Flags override matching keys from the file,\nand each override is reported in `meta.warnings`.\n\n```bash\ntoil jira issue schema --example-only > envelope.json # the example is in .data\ntoil jira issue create --input-file issue.json --priority Low --allow-write\n```\n\nOver MCP, `-` is refused because stdin carries the protocol; pass a file path.\nRelative paths resolve against the directory toil runs in.\n\n## Custom fields\n\n`--field Name=value` (repeatable), `--fields-file` and `--input-file` accept a raw field\nid (`customfield_10032`) or a standard field name (`fixVersions`) with no setup.\n`Name=@file.json` reads the value from a file: JSON when it parses, text otherwise, which\nalso avoids shell quoting trouble in PowerShell.\n\nTo use a **friendly name** in flags, JQL and output, register the field on the\nconnection:\n\n```json\n"customFields": [{ "id": "customfield_10016", "name": "Story Points", "type": "number" }]\n```\n\n`type` shapes a `--field` value: `string`, `number`, `date`, `datetime`, `select`\n(`{value}`), `multi-select`, `option-id` (`{id}`), `cascading-select` (`parent` or\n`parent:child` ids), `user` (`{name}`), `labels`, `url`, `textarea`. Omit it to send the\nraw string. `toil jira issue fields --discover` lists Jira\'s fields with a `suggestedType`; add\n`--project ABC` to see each select field\'s `allowedValues`. A select field that only\naccepts option ids needs `"type": "option-id"`. **Sprint is not a custom field**: use\n`issue set-sprint` after the issue exists.\n\nA **dossier** can name fields too (`"jira": { "fields": { "storyPoints": "customfield_10016" } }`,\nor `toil dossiers field <dossier> jira storyPoints customfield_10016`). Then\n`issue create` and `issue update` take `--field storyPoints=5` in any folder the dossier\napplies to. An alias takes the type the connection registers for that id. A name the\nconnection already uses keeps the connection\'s meaning.\n\n## Data Center, not Cloud\n\nThis area targets Jira Data Center and Server. Users are **usernames** (`--assignee\njsmith`, `user`-typed fields send `{ "name": ... }`), where Jira Cloud needs an\n`accountId`. Jira Cloud is a separate area, `jira-cloud`, with its own\n`TOIL_JIRA_CLOUD_*` settings; don\'t point this one at a Cloud site.\n\n## Ticket the work\n\nBefore starting work no ticket covers, rank your open issues against it:\n\n```bash\ntoil jira issue search --jql "assignee = currentUser() AND statusCategory != Done" --fields summary,description,status,issuetype,labels,parent | toil util owi map | toil util owi similar --query "Card payments time out at checkout"\n```\n\nThen ask the person, as `core.md`, **Ticket the work**, says: attach the work to a\nmatch (nothing is written), create a sub-task under it, or create a new ticket. A\nsub-task is\n`toil jira issue create --type Sub-task --parent PAY-12 --summary "<text>" --allow-write`\n(the project may name the type differently); a new ticket takes the project and type\nfrom the dossier and the connection. Both are writes, made only on the person\'s yes.\n\n## Notes\n\n- `issue create` doesn\'t check for duplicates. After a timeout, search for the summary\n before retrying: the issue may already exist.\n- `issue update` with nothing to change still sends an empty update and reports\n `{ updated }`.\n- `issue download` never replaces a file. If one of the same name is already in the target directory, it fails with `INVALID_INPUT`; delete the file or pass a different `--dir`.\n- `issue download` saves a name Windows would read as another file under one it won\'t: a device name such as `CON` or `nul.txt` gets a leading `_`, a `:` and what follows it is dropped, as are trailing dots and spaces, and the characters Windows forbids become `_`. `filename` is still the name Jira gave; `saved` is where the file went. The same holds on every platform.\n- `issue download` only ever sends the token to `baseUrl`\'s host. If Jira names\n another host for the file, toil fetches the same path from `baseUrl` and warns.\n- Issue keys and ids are sent as one URL path segment each, encoded, so a `/` or `?` in\n one can\'t change the endpoint called. A project key from `--project`, the\n connection\'s `project` setting, a dossier or `--input-file` that holds `/`, `\\`, `?`,\n `#`, `%` or a control character is refused with `INVALID_INPUT`.\n',
140339
140442
  "kibana.md": '---\narea: kibana\ndescription: Kibana status, spaces, dashboards (list and NDJSON export), data views and alerting rules, read with an API key\n---\n\n# Kibana (`kibana`)\n\nStatus, spaces, dashboards, data views and alerting rules on **Kibana**, through its\nREST API. Every command reads; none changes anything. Verification level: `unit`.\n\n**Supported versions:** The oldest Kibana version toil supports hasn\'t been established. `status` reads both the 7.x (`state`/`title`) and the 8.x\n(`level`/`summary`) shapes; `data-view list` calls `/api/data_views`, which Kibana\nadded in 8.0, so on 7.x it fails with `NOT_FOUND`. Requests follow Elastic\'s current\nKibana API reference. No release has been verified yet.\n\n## Credential\n\nA Kibana or Elasticsearch **API key**: in Kibana, Stack Management \u2192 API keys \u2192\nCreate API key. Copy the **encoded** value, shown once when the key is created, and\ngive it access to the Kibana features you\'ll read (dashboards, data views, alerting).\ntoil sends it as `Authorization: ApiKey <encoded>`, with `kbn-xsrf: true`, only to\nthe connection\'s `baseUrl`. There is no username, password or browser login.\n\n## Configuration\n\n| Key | Env var | Required | Meaning |\n|-----|---------|----------|---------|\n| `baseUrl` | `TOIL_KIBANA_BASE_URL` | yes | Kibana root, e.g. `https://kibana.imagile.dev` (keep any context path, such as a `basePath`). Kibana itself, not Elasticsearch |\n| `apiKey` | `TOIL_KIBANA_API_KEY` | no | The encoded API key. Unset, the paired Elasticsearch connection\'s key is used (below) |\n| `space` | `TOIL_KIBANA_SPACE` | no | Default space id for the space-scoped commands; unset or `default` is the default space |\n| `apiKeyFrom` | `TOIL_KIBANA_API_KEY_FROM` | no | The Elasticsearch connection whose `apiKey` this connection uses when it has none of its own |\n\nThere\'s no CI fallback variable.\n\nEnvironment variables (CI, or a one-off shell):\n\n```bash\nexport TOIL_KIBANA_BASE_URL=https://kibana.imagile.dev\nexport TOIL_KIBANA_API_KEY=<your encoded API key>\nexport TOIL_KIBANA_SPACE=ops # optional\n```\n\nOr `~/.toil/config.json`:\n\n```json\n{\n "version": 2,\n "connections": {\n "kibana-prod": { "area": "kibana", "baseUrl": "https://kibana.imagile.dev", "space": "ops" }\n },\n "defaults": { "kibana": { "connection": "kibana-prod" } }\n}\n```\n\nThe key never goes in this file; a plaintext one there is refused with\n`CONFIG_INVALID`. Run `toil connections add kibana-prod --area kibana` (or\n`toil connections login kibana-prod` for an existing connection) to keep it in the\nOS credential store, or set `TOIL_KIBANA_API_KEY`.\n\n### Using the Elasticsearch key\n\nOne key often serves both. A Kibana connection uses an Elasticsearch connection\'s\n`apiKey` only when you pair them, by naming that connection in `apiKeyFrom`:\n\n```json\n{\n "version": 2,\n "connections": {\n "es-prod": { "area": "elasticsearch", "baseUrl": "https://elasticsearch.imagile.dev" },\n "kibana-prod": { "area": "kibana", "baseUrl": "https://kibana.imagile.dev", "apiKeyFrom": "es-prod" }\n }\n}\n```\n\nAn unpaired connection never gets another area\'s key, with one exception, an env\nfallback the contract specifies: Kibana\'s default connection takes `TOIL_ELASTICSEARCH_API_KEY`\nwhen `TOIL_KIBANA_API_KEY` isn\'t set. Which key wins: an env value beats a stored\none, and within a tier Kibana\'s own key wins. The borrowed key is still sent only to\nKibana\'s `baseUrl`, never to Elasticsearch\'s. `meta.context.shared` says when the key\ncame from Elasticsearch (the connection, and env or store, never the value), and a\n401 or 403 while sending it says so in the error: such a key may lack Kibana\nprivileges, so give that Kibana connection its own key with\n`toil connections login <name>` (or `TOIL_KIBANA_API_KEY` for the default connection).\n\nWith no key at all, commands fail with `NOT_CONFIGURED`, naming both ways to set one.\n\n## Commands\n\n`--space <id>` on `dashboard`, `data-view` and `rule` commands picks the space, falling back\nto the connection\'s `space`; the default space has no URL prefix, any other is\n`/s/<id>/api/...`. Each of those commands reports `space` as the id used, or\n`default`. `status` and `space list` are never space-scoped.\n\n- `status`: Show Kibana version and overall status. `data` is `{ name, uuid,\n version, buildFlavor, status, summary }`. An unhealthy Kibana answers 503 with its\n status in the body, and that\'s a successful answer (`status` `unavailable`, say); a\n 503 without Kibana\'s own status, such as a proxy\'s, is an `HTTP` error.\n- `space list`: List the spaces the API key can see. `data` is `{ count, spaces }`,\n each `{ id, name, description, disabledFeatures }`.\n- `dashboard list`: List dashboards (id, title, description, last updated).\n `--search` matches titles (a trailing `*` is a wildcard). One page per call:\n `--page` (default 1) and `--page-size` (default 100), each a whole number of at\n least 1. `data` is `{ space, total, page, perPage, count, dashboards }`; ask for the\n next page while `page \xD7 perPage < total`. Kibana marks the API it uses\n (`_find`) as deprecated, though it still serves it.\n- `dashboard export <id...>`: Export dashboards as saved objects, including the\n visualizations and data views they reference. It takes one or more ids;\n `--no-references` exports only the dashboards. `data` is `{ space, count,\n exportDetails, objects }`: the saved objects as Kibana exported them, and its\n closing summary (`exportedCount`, `missingRefCount`, `missingReferences`). Sent as a\n POST; it still only reads.\n- `data-view list`: List data views (id, name, index pattern). `data` is `{ space,\n count, dataViews }`, each `{ id, name, pattern, namespaces }`; a view with no name\n is named by its pattern.\n- `rule list`: List alerting rules with their schedule and last execution status.\n `--search` matches names; `--page` and `--page-size` as for `dashboard list`. Each\n rule is `{ id, name, ruleTypeId, consumer, enabled, muted, tags, interval,\n executionStatus, lastExecutionDate, lastRunOutcome, error, nextRun, updatedAt }`.\n- `rule get <id>`: Get one alerting rule, including its params and actions. `data` is the same summary plus `params` and `actions`.\n\n`status` and `dashboard export` hand a 429 back at once; the other commands retry it.\n\n```bash\ntoil kibana status\ntoil kibana space list\ntoil kibana dashboard list --search "payments*" --space ops\ntoil kibana dashboard export abc12345 abc12346 --no-references\ntoil kibana data-view list\ntoil kibana rule list --search "High*" --page-size 20\ntoil kibana rule get abc12345-0000-0000-0000-000000000000\n```\n',
140340
140443
  "logscale.md": '---\narea: logscale\ndescription: Query Language searches and repository lists on Falcon LogScale\n---\n\n# Falcon LogScale (`logscale`)\n\nSearches a Falcon LogScale repository with the LogScale Query Language, and lists\nthe repositories a token can see. Both commands read; neither changes anything.\nBuilt from LogScale\'s API documentation. Verification level: `unit`.\n\n**Supported versions:** The oldest Falcon LogScale version toil supports hasn\'t been established. toil\ncalls the synchronous Search API (`/api/v1/repositories/<repo>/query`) and the\nGraphQL `repositories` query (`/graphql`), with the token sent as a Bearer header.\nNo release has been verified yet.\n\n## Credential\n\nA LogScale **personal API token**: in LogScale, your account settings \u2192 Personal\nAPI Token. A token with read access to the repository also works for `repository query`;\n`repository list` lists what the token\'s user can see. toil sends it as\n`Authorization: Bearer <token>`. There is no username, password or browser login.\n\n## Configuration\n\n| Key | Env var | Required | Meaning |\n|-----|---------|----------|---------|\n| `baseUrl` | `TOIL_LOGSCALE_BASE_URL` | yes | LogScale server root, e.g. `https://logscale.imagile.dev` (keep any context path) |\n| `token` | `TOIL_LOGSCALE_TOKEN` | yes | Personal API token |\n\nThere is no CI fallback variable.\n\n```bash\nexport TOIL_LOGSCALE_BASE_URL=https://logscale.imagile.dev\nexport TOIL_LOGSCALE_TOKEN=<your personal API token>\n```\n\nOr `~/.toil/config.json`:\n\n```json\n{\n "version": 2,\n "connections": {\n "corp-logscale": { "area": "logscale", "baseUrl": "https://logscale.imagile.dev" }\n },\n "defaults": { "logscale": { "connection": "corp-logscale" } }\n}\n```\n\nThe token never goes in this file; a plaintext one there is refused with\n`CONFIG_INVALID`. Run `toil connections add corp-logscale --area logscale` (or\n`toil connections login corp-logscale`) to keep it in the OS credential store, or set\n`TOIL_LOGSCALE_TOKEN`.\n\n## Commands\n\n- `repository list`: List available repositories. `data` is `{ count,\n repositories }`, each with `id`, `name`, `description` and `timeOfLatestIngest`\n from the GraphQL `repositories` query.\n- `repository query <repository>`: Execute a LogScale Query Language (LQL) search\n against a repository. `--query` is required.\n - `--start` (default `1h`) and `--end` (default `now`) take epoch milliseconds, an\n ISO 8601 date or date-time (UTC unless it carries an offset), or a relative time\n such as `1h`, `24hours` or `2days`. ISO 8601 is sent as epoch milliseconds.\n - `--limit` (default 200) is the most events returned. LogScale\'s search has no\n limit field, so toil keeps the first N of what came back and adds a\n `LOGSCALE_LIMIT` warning when there were more. To have LogScale itself return\n fewer, end the query with `| head(N)` or `| tail(N)`.\n - `--timeout-ms` (default 30000, at most 600000) is how long toil waits for the\n answer. A slower answer is `TIMEOUT`.\n - `data` is `{ repository, done, cancelled, eventCount, events, warnings,\n metaData }`. The synchronous search answers with the finished result, so `done`\n is `true`, `cancelled` is `false`, `warnings` is `[]` and `metaData` is `null`.\n Event field values are strings, except `@timestamp`, which is epoch\n milliseconds.\n\nLogScale recommends this synchronous search for filter queries over short windows.\nAn aggregate (`| count()`) works, but blocks until the whole window is searched.\n\nA query LogScale rejects (a syntax error) is `HTTP`, with LogScale\'s explanation\nafter the status, such as `HTTP 400 Bad Request: Unexpected end of input at 1:7`.\n\n```bash\ntoil logscale repository list\ntoil logscale repository query imagile-app --query \'level=error\' --start 15m\ntoil logscale repository query imagile-app --query \'level=error | count()\' --start 2026-10-01T00:00:00Z --end 2026-10-02T00:00:00Z\n```\n',
140341
140444
  "mcp.md": '---\ndescription: Running toil as an MCP server over stdio, the tools and resources it serves, and registering it with Claude Code, Codex, VS Code and other clients\n---\n\n# toil as an MCP server\n\n`toil mcp` serves every toil command as an MCP tool over stdio. It\'s the same core as\nthe CLI, with the same inputs and the same envelope. A tool\'s name is its command path\nwith underscores: `toil jira issue get` is `jira_issue_get`. It never opens a network\nport.\n\n- **`--areas jira,confluence`** serves exactly those areas, so an agent sees a short\n tool list and one server entry stands in for one vendor\'s server. Commands outside\n an area are areas of their own here: add `version` or `connections` to the list to\n serve them too. Without `--areas`, toil serves every area that has a connection set\n up, plus every command that needs none (`version`, `connections list`,\n `jira issue schema`).\n- **Writes**: a write tool is listed only when one of its area\'s connections has\n `writes: true`, and every call still needs `allowWrite: true`. Deletes, and the\n commands that prompt or change connections (`connections add`, `setup alias`), are\n never tools.\n- **Big results**: every tool takes `outputFormat` (`"toon"` writes `data` as compact\n TOON text) and `summaryFile` (the whole of `data` goes to that file in the\n workspace, and a summary comes back in its place), as `core.md`, **Big results**,\n describes.\n- **Files**: a command that reads or writes a file needs a workspace: `--workspace\n <dir>` in the server\'s args, else `TOIL_WORKSPACE`, else the client\'s root when it\n shares exactly one. With none, it returns `NOT_CONFIGURED`.\n- **`wait`**: the `wait` tool repeats one read tool until a condition over its data\n holds (`SKILL.md` describes it). It\'s served whenever a read tool is, `--areas` or\n not, and repeats only the tools the server serves. After every attempt that doesn\'t\n end the wait it sends a progress notification when the call carried a progress\n token, so a client that resets its tool-call timeout on progress keeps a long wait\n alive. The notifications are checked with the MCP TypeScript SDK\'s client\n (`resetTimeoutOnProgress`), and the Codex CLI ran a one-minute wait to its end.\n Whether Claude Code, Codex or other clients reset their own tool-call timeout on\n progress hasn\'t been checked, so with those keep `timeout` under the client\'s\n tool-call limit.\n- **Progress**: any tool call that carried a progress token also gets a progress\n notification for each page a listing reads and each rate-limited (429) request\n toil waits to retry, with the same message the CLI writes to stderr\n (`core.md`, **Progress**). The envelope is the same either way.\n- **Resources**: besides tools, the server serves read-only resources that describe\n toil\'s own context, so a client can read it without a tool call. None reads from a\n service, and none holds a secret. They follow `--areas` as the tools do.\n - `toil://connections`: each connection\'s `name`, `area`, `isDefault` and\n `writes`, for the areas served. Never a host or a credential.\n - `toil://dossiers` and `toil://dossiers/<name>`: what the `dossiers_list` and\n `dossiers_show` tools return, served when those tools are.\n - `toil://skill/<area>`: this skill\'s page for each area served, such as\n `toil://skill/jira` for `jira.md`.\n- **Config**: the server reads `~/.toil/config.json`, or `--config <file>` in its args,\n and the `TOIL_*` env vars it is started with. Keep tokens in the OS credential\n store (`toil connections add`, run once on a terminal) rather than in the client\'s\n `env` block, which is a file someone may share or commit.\n\n## Registering it\n\nThe examples use `toil` on PATH and the Jira area; change `--areas` to what the task\nneeds.\n\n**Claude Code**\n\n```bash\nclaude mcp add toil -- toil mcp --areas jira\n```\n\n**Codex**\n\n```bash\ncodex mcp add toil -- toil mcp --areas jira\n```\n\nor in `~/.codex/config.toml`:\n\n```toml\n[mcp_servers.toil]\ncommand = "toil"\nargs = ["mcp", "--areas", "jira"]\n```\n\n**VS Code and GitHub Copilot**, in `.vscode/mcp.json`:\n\n```json\n{ "servers": { "toil": { "type": "stdio", "command": "toil", "args": ["mcp", "--areas", "jira"] } } }\n```\n\n**Claude Desktop, Cursor and other clients with an `mcpServers` file**:\n\n```json\n{ "mcpServers": { "toil": { "command": "toil", "args": ["mcp", "--areas", "jira"] } } }\n```\n\n## When `toil` isn\'t on PATH\n\nMCP clients start servers without a shell, so they don\'t read shell profiles and a\n`toil` alias doesn\'t apply. Use one of these as the command and its args instead:\n\n| Installed | `command` | `args` |\n|-----------|-----------|--------|\n| From a clone | `node` | `["<clone>/dist/toil.js", "mcp", "--areas", "jira"]`, with the clone\'s absolute path |\n| Not at all, once toil is on npm | `npx` | `["-y", "@imagile-dev/toil", "mcp", "--areas", "jira"]` |\n| From npm, on Windows | `cmd` | `["/c", "toil", "mcp", "--areas", "jira"]`, because npm\'s `toil.cmd` needs a shell to start |\n\nIn JSON and TOML, write a Windows path with forward slashes\n(`C:/Users/you/toil/dist/toil.js`), which Node accepts.\n\n## Checking it works\n\nAsk the agent to list toil\'s tools and call one that needs no connection: `version`\n(served when `--areas` is left out or names `version`) returns the same envelope as\n`toil version`, `{ "ok": true, "data": { "version": \u2026 } }`. A tool that isn\'t listed\nis in an area `--areas` leaves out, in an area with no connection set up (without\n`--areas`), or a write tool on a connection without `writes: true`.\n',
@@ -140344,11 +140447,11 @@ var skillFiles = {
140344
140447
  "osv.md": '---\narea: osv\ndescription: Known vulnerabilities for a dependency inventory, from the public OSV.dev API\n---\n\n# OSV.dev (`osv`)\n\nKnown vulnerabilities for the packages in a dependency inventory, from Google\'s\npublic **OSV.dev** API (`https://api.osv.dev`). It reads only and needs no\nconnection. Verification level: `unit`.\n\n**Supported versions:** OSV API v1 or later\n\n## Credential and configuration\n\nNone. OSV.dev is a public API, and the command names it, so toil talks to\n`https://api.osv.dev` and nothing else. There is no connection to add, no `TOIL_OSV_*`\nvariable and no `--connection` flag. toil uses `HTTPS_PROXY`, `HTTP_PROXY` and\n`NO_PROXY` when they\'re set.\n\n## Commands\n\n### `toil osv vulns`\n\nChecks an inventory, a JSON list of packages, against OSV.dev. MCP tool: `osv_vulns`.\n\n```bash\necho \'[{"name":"lodash","version":"4.17.20","ecosystem":"npm"}]\' > inventory.json\ntoil osv vulns --from inventory.json\ntoil osv vulns --from inventory.json --ecosystem npm --direct-only\n```\n\n| Flag | Meaning |\n|------|---------|\n| `--from <file>` | A JSON file holding a list of `{ name, version, ecosystem }` packages (`ecosystem` is `npm`, `nuget` or `maven`; Maven names are `group:artifact`). Optional `type` (`direct`/`transitive`) and `scope` (`production`/`dev`) feed the filters below. `toil deps scan` output (its envelope or its `data`) is accepted too, so `toil deps scan | toil osv vulns` works. Omitted, the inventory is read from stdin on the CLI. Over MCP pass `from`; there is no stdin |\n| `--ecosystem <ecosystem>` | `npm`, `nuget`, `maven` or `all` (default). Any other value matches nothing and returns a clean result |\n| `--direct-only` | Leave out packages the inventory marks `transitive` |\n| `--include-dev` | Keep packages the inventory marks `dev` (left out by default) |\n\nIt first checks OSV.dev answers (an empty batch), then sends `POST /v1/querybatch`\nwith up to 500 packages a request, one request after another. Ecosystems go as\n`npm`, `NuGet` and `Maven`; Maven names are `group:artifact`.\n\nOutput, the same shape `deps frisk` had:\n\n```json\n{\n "tier": "full", "source": "osv", "sourcesQueried": ["osv"], "sourceErrors": [],\n "scanned": 4, "vulnerable": 1,\n "packages": [{\n "name": "lodash", "version": "4.17.20", "ecosystem": "npm", "source": "package-lock.json", "type": "direct", "scope": "production",\n "vulnerabilities": [{\n "id": "GHSA-35jh-r3h4-6jhm", "summary": "Command Injection in lodash", "severity": "HIGH", "cvss": null, "aliases": ["CVE-2021-23337"],\n "remediation": { "fixAvailable": true, "fixedVersions": ["4.17.21"], "advice": "Upgrade lodash to 4.17.21" },\n "references": ["https://github.com/advisories/GHSA-35jh-r3h4-6jhm"]\n }]\n }]\n}\n```\n\nOSV\'s batch query answers with vulnerability ids only, so toil then fetches each\ndistinct id\'s full record (`GET /v1/vulns/<id>`, eight at a time) and fills\n`summary`, `severity`, `cvss`, `aliases`, `references` and the fix from it.\n`fixedVersions` collects the `fixed` events of every affected package in the record,\nand `severity` is the record\'s `database_specific.severity` as given (GHSA uses\n`MODERATE`), so read the advice against the advisory for multi-package records.\n\n## Errors\n\n- `INVALID_INPUT`: the inventory isn\'t JSON, is a failed result, has no packages\n list, or has a package without a name, version or ecosystem. Nothing is sent.\n- `NETWORK`: "toil osv vulns requires OSV.dev access but api.osv.dev is not reachable\n from this machine." The reachability check failed; `error.details.cause` says how.\n- `HTTP`: `OSV.dev returned HTTP <status> <reason>` for a batch that failed, and\n `OSV.dev returned HTTP <status> <reason> for <id>` (`NOT_FOUND` for a 404) for a record that couldn\'t\n be fetched.\n\n## Alias paths\n\n`deps frisk` (the default source) and `deps frisk --source osv` run `toil osv vulns`, with the same\n`--ecosystem`, `--direct-only`, `--include-dev` and `--from` flags.\n',
140345
140448
  "saucelabs.md": '---\narea: saucelabs\ndescription: Sauce Labs test jobs, builds, real devices and device sessions, tunnels, platforms, app storage metadata and teams\n---\n\n# Sauce Labs (`saucelabs`)\n\nTest jobs on virtual devices and desktop browsers, real-device jobs, builds, the\nreal-device catalog, Real Device Access sessions (reserve a device, open URLs,\ninstall apps, run ADB shell commands, record tests, throttle the network, start\nAppium), Sauce Connect tunnels, app storage metadata and teams, on **Sauce Labs**.\nVerification level: `unit`.\n\n**Supported versions:** The oldest Sauce Labs version toil supports hasn\'t been established. Sauce Labs is\nSaaS only, so there is no server release to pin. toil calls the REST v1 and v1.2,\nReal Device Access v2, Builds v2, Team Management v1 and Storage v1 APIs on the\ndata-center host in `baseUrl`. Nothing has been verified against a live account yet.\n\n## Credential\n\nYour Sauce Labs **username and access key**: in Sauce Labs, User settings \u2192 Access\nkey. toil sends them as `Authorization: Basic base64(username:accessKey)`, and puts\nthe username in most `/rest/v1/<username>/...` paths. There is no token exchange,\npassword or browser login. `toil saucelabs concurrency` is the cheapest check that\nthe two belong together: Sauce has no "current user" endpoint, and that one is\nscoped to the username.\n\n## Configuration\n\n| Key | Env var | Required | Meaning |\n|-----|---------|----------|---------|\n| `baseUrl` | `TOIL_SAUCELABS_BASE_URL` | yes | Your account\'s data-center API endpoint, e.g. `https://api.us-west-1.saucelabs.com` (`https://api.eu-central-1.saucelabs.com` in the EU). There\'s no default |\n| `username` | `TOIL_SAUCELABS_USERNAME`, then `SAUCE_USERNAME` | yes | Sauce Labs username |\n| `accessKey` | `TOIL_SAUCELABS_ACCESS_KEY`, then `SAUCE_ACCESS_KEY` | yes | Access key |\n\n**CI fallbacks:** when `TOIL_SAUCELABS_USERNAME` or `TOIL_SAUCELABS_ACCESS_KEY` isn\'t\nset, the default connection takes the value from `SAUCE_USERNAME` or\n`SAUCE_ACCESS_KEY`, the variables saucectl, Sauce Connect and Sauce\'s own CI docs\nread. Each sits directly below its `TOIL_` variable and above the config file.\nThere\'s no fallback for the base URL.\n\nEnvironment variables (CI, or a one-off shell):\n\n```bash\nexport TOIL_SAUCELABS_BASE_URL=https://api.us-west-1.saucelabs.com\nexport TOIL_SAUCELABS_USERNAME=<your username>\nexport TOIL_SAUCELABS_ACCESS_KEY=<your access key>\n```\n\nOr `~/.toil/config.json`:\n\n```json\n{\n "version": 2,\n "connections": {\n "sauce": { "area": "saucelabs", "baseUrl": "https://api.us-west-1.saucelabs.com", "username": "imagile" }\n },\n "defaults": { "saucelabs": { "connection": "sauce" } }\n}\n```\n\nThe access key never goes in this file; a plaintext one there is refused with\n`CONFIG_INVALID`. Run `toil connections add sauce --area saucelabs` (or\n`toil connections login sauce` for an existing connection) to keep it in the OS\ncredential store, or set `TOIL_SAUCELABS_ACCESS_KEY`.\n\n## Commands\n\nIds are positional arguments: `<job-id>`, `<build-id>`, `<device-id>`,\n`<session-id>`, `<tunnel-id>`, `<team-id>`. Over MCP they\'re fields (`jobId`,\n`sessionId`, ...). Enum values are matched ignoring case. Integer flags take whole\nnumbers 0 or more. Time flags (`--from`, `--to`, `--start`, `--end`) take Unix\nseconds or an ISO 8601 date; give the date-time an offset (`2026-09-01T00:00:00Z`),\nbecause one without is read in the machine\'s local time zone.\n\nAccount and platform:\n\n- `status`: Sauce Labs service status (operational flag, wait time)\n- `concurrency`: Concurrency allowed and in use for your organization and team (also verifies credentials)\n- `platform list`: Supported OS/browser/device platforms (`--api all|appium|webdriver`, default `all`); `data` is `{ api, count, platforms }`\n- `appium-version list`: Appium versions available for real-device sessions, with end-of-life dates\n- `user list`: Look up users in your organization (`--username`, `--phrase`, `--limit` (default 20, max 100), `--offset`)\n\nJobs on virtual devices and desktop browsers, under your username:\n\n- `job list`: List your recent jobs (`--limit`, `--offset`, `--from`, `--to`); `data` is `{ count, jobs }`\n- `job get`: Get one job: status, platform, timings, and log/video URLs\n- `job update`: Update a job\'s name, build, tags, result, or visibility (`--name`, `--build`, `--tags` (repeatable or comma-separated; replaces the existing tags), `--passed` or `--failed`, `--public public|public restricted|share|team|private`). At least one is required, checked before any request\n- `job stop`: Stop a running job\n- `job delete`: Delete a job and all of its assets; `data` is `{ jobId, deleted: true }`\n- `job assets`: List the asset files a job produced (logs, video, screenshots) \u2014 names only, no download; `data` is `{ jobId, assets }`\n\nReal-device jobs:\n\n- `rdc-job list`: List real-device jobs (`--limit`, `--offset`, `--live` for manual tests only)\n- `rdc-job get`: Get one real-device job: device, result, timings, and log URLs\n- `rdc-job update`: Update a real-device job\'s name, build, tags, or result (`--name`, `--build`, `--tags`, `--passed` or `--failed`)\n- `rdc-job stop`: Stop a running real-device job; `data` is `{ jobId, stopped: true }`\n- `rdc-job delete`: Delete a real-device job (owner, team admin, or org admin only); `data` is `{ jobId, deleted: true }`\n\nBuilds (`--source vdc|rdc`, default `vdc`):\n\n- `build list`: List builds (`--status` repeatable or comma-separated, each sent as its own `status=` parameter: running, error, failed, complete, success; `--name`, `--start`, `--end`, `--limit`, `--offset`, `--sort asc|desc`); `data` is `{ source, count, builds }`\n- `build get`: Get one build with its job counts\n- `build jobs`: List the jobs in a build (`--failed`, `--errored`, `--passed`, `--running`, `--queued`, `--completed`, `--finished`, `--faulty`, `--modified-since`, which is sent as typed); `data` is `{ buildId, source, count, jobs }`\n- `job build <job-id>`: Get the build a job belongs to\n\nReal devices:\n\n- `device list`: List real devices your account can use (`--name` regex, `--os android|ios`, `--os-version`, `--type phone|tablet`); `data` is `{ count, devices }`\n- `device get`: Get one device\'s full descriptor (hardware, OS, screen)\n- `device status`: Live availability of real devices (AVAILABLE, IN_USE, CLEANING, ...) (`--state`, `--name`, `--private-only`)\n\nReal-device sessions (Real Device Access API):\n\n- `session list`: List your device sessions (`--state`, `--device-name`); `data` is `{ count, sessions }`\n- `session create`: Reserve a real device. Returns immediately in PENDING state unless --wait is passed (`--device-name`, `--os android|ios`, `--tunnel-name`, `--tunnel-owner` (needs `--tunnel-name`), `--duration` as ISO 8601, e.g. `PT30M`). `--wait` polls every 5 s until the session is ACTIVE, and fails if it closes or errors, or when it\'s still starting after `--timeout` seconds (default 300). It gives up when the next poll would land past the timeout, so up to 5 s early; the session keeps starting in the background. The command\'s time limit is an hour (`TOIL_TIMEOUT_MS` overrides it)\n- `session get`: Get a session: state, device, expiry, Appium URL, and live-view link\n- `session delete`: Close a session and release the device (`--reboot`, private devices only)\n- `session open-url`: Open a URL on the device (Chrome on Android; Safari or a deep link on iOS): `session open-url <session-id> <url>`\n- `session shell`: Run an ADB shell command on an Android device (public devices allow only a safe subset): `session shell <session-id> <command>`; `data` is `{ sessionId, command, stdout }`. It waits up to 120 s for the device\n- `session install-app`: Install an app from Sauce app storage onto the device (runs in the background): `session install-app <session-id> <app>`, where `<app>` is `storage:<file-id>` or `storage:filename=<name>` (`--launch`, `--no-instrumentation`)\n- `session installations`: List app installations on the device and their status\n- `session launch-app`: Launch an installed app (exactly one of `--bundle-id` or `--package-name`; `--activity` needs `--package-name`)\n- `session uninstall-app`: Uninstall an app (exactly one of `--bundle-id` or `--package-name`)\n- `session settings`: Change device settings: orientation (both), locale and animations (Android only) (`--orientation portrait|landscape`, `--locale`, `--animations on|off`); `data` is `{ sessionId, applied }`\n- `session start-test`: Start recording a test (a job) inside the session (`--name`, `--build`, `--tags`, `--video`, `--device-logs`, `--network-capture`, `--screenshots`, `--appium-logs`)\n- `session end-test`: End the active test in the session, optionally recording its result (`--passed` or `--failed`)\n- `session tests`: List the tests recorded in a session, with links to each job\n- `session network-profiles`: List the network throttling profiles available to a session\n- `session network`: Throttle the device network with a named profile or explicit conditions, or --reset to clear (exactly one mode: `--profile`, `--reset`, or any of `--download` and `--upload` (0-50000 kbps), `--latency` (0-3000 ms) and `--loss` (0-100 %))\n- `session appium`: Get the session\'s Appium server URL, or --start one (`--appium-version` needs `--start`)\n\nSauce Connect tunnels, under your username:\n\n- `tunnel list`: List your tunnels with full details (`--all` adds tunnels shared with you). With `--all` Sauce may answer with an object keyed by owner, in which case `data.tunnels` is that object and `count` is absent\n- `tunnel get`: Get one tunnel\n- `tunnel jobs`: Number of jobs currently running through a tunnel\n- `tunnel stop`: Shut down a tunnel\n\nApp storage (metadata only; no upload or download):\n\n- `storage files`: List uploaded app files (`--query`, `--kind android|ios`, `--page` (starts at 1), `--page-size` (max 100))\n- `storage groups`: List app groups (all versions of one app), with the same flags\n\nTeams:\n\n- `team list`: List teams (`--name` prefix)\n- `team get`: Get one team and its settings\n- `team members`: List a team\'s members\n\nLists are one request each, with the paging parameters passed straight through;\n`count` is the length of the list Sauce returned, and is absent when the answer\nisn\'t a list. Sauce\'s error bodies (`{ "detail": "..." }`) become the error message.\n\n## Writes\n\n`job update`, `stop` and `delete`; `rdc-job update`, `stop` and `delete`; `tunnel\nstop`; and every `session` command that acts on a device (`create`, `delete`,\n`open-url`, `shell`, `install-app`, `launch-app`, `uninstall-app`, `settings`,\n`start-test`, `end-test`, `network`, `appium`) change something in Sauce Labs. Each\nneeds `writes: true` on the connection and `--allow-write` on the call. `session\nappium` needs both even to read the URL, because the same command can start a server.\n\n`job delete`, `rdc-job delete`, `session delete` and `tunnel stop` delete something, so\nthey run on the CLI only and are never MCP tools.\n\n```bash\ntoil saucelabs concurrency\ntoil saucelabs job list --limit 20 --from 2026-09-01T00:00:00Z\ntoil saucelabs build list --source rdc --status failed,error\ntoil saucelabs session create --device-name "iPhone 15.*" --os ios --wait --allow-write\ntoil saucelabs session shell <session-id> "getprop ro.build.version.release" --allow-write\n```\n',
140346
140449
  "sde.md": '---\narea: sde\ndescription: Projects, countermeasures (tasks), threats and users on SD Elements, read through its REST API v2\n---\n\n# SD Elements (`sde`)\n\nProjects, countermeasures (tasks), threats and users on **SD Elements**, through its\nREST API v2 (`/api/v2/...`). Every command reads; none changes anything.\nVerification level: `unit`.\n\n**Supported versions:** The oldest SD Elements version toil supports hasn\'t been established. toil\ncalls `/api/v2/` with an API token sent as `Authorization: Token`. `server-info`\nreports the version but needs a super-user, so toil makes no version check. No\nrelease has been verified yet.\n\n## Credential\n\nAn SD Elements **API token**: in SD Elements, your user menu \u2192 API Tokens. toil sends\nit as `Authorization: Token <token>`. There is no username, password or browser\nlogin, and no CI fallback variable.\n\n## Configuration\n\n| Key | Env var | Required | Meaning |\n|-----|---------|----------|---------|\n| `connectionString` | `TOIL_SDE_CONNECTION_STRING` | yes | API token and server host in one value, `<token>@<host>` |\n| `project` | `TOIL_SDE_PROJECT` | no | Default project ID for `project get`, `task list`, `task get` and `threat list` |\n\n**The connection string** holds both the token and the host:\n`abc12345@sde.imagile.dev`, or `abc12345@imagile.sdelements.com` for a hosted\ntenant. toil splits it at the first `@`, and the host gets `https://` unless it\nalready has a scheme (`abc12345@https://sde.imagile.dev/sde` keeps a context path).\nA value with no `@`, or with `@` first, sets nothing, and commands fail with\n`NOT_CONFIGURED`. An env value beats the config file.\n\nEnvironment variables (CI, or a one-off shell):\n\n```bash\nexport TOIL_SDE_CONNECTION_STRING=<your API token>@sde.imagile.dev\n```\n\nOr `~/.toil/config.json`, with `project` usually set once under `defaults.sde`:\n\n```json\n{\n "version": 2,\n "connections": {\n "corp-sde": { "area": "sde" }\n },\n "defaults": { "sde": { "connection": "corp-sde", "project": "42" } }\n}\n```\n\nThe connection string holds the token, so it never goes in this file; a plaintext\none there is refused with `CONFIG_INVALID`. Run `toil connections add corp-sde --area sde`\n(or `toil connections login corp-sde` for an existing connection) to keep it in the\nOS credential store, or set `TOIL_SDE_CONNECTION_STRING`.\n\n## Commands\n\nThe project ID comes from `--project <id>` (or the `[id]` argument of `project get`), else the\nconnection\'s `project` (usually `defaults.sde.project`). With neither, the command\nfails with "No project specified"; anything but a positive whole number fails with\n"Invalid project ID". Both happen before any request.\n\n- `server-info`: Get server version and platform info. SD Elements answers only a\n super-user.\n- `whoami`: Get current authenticated user (`/api/v2/users/me/`).\n- `user list`: List users (`--email`, `--first-name`, `--last-name`, `--active true|false`).\n- `project list`: List projects (`--name`, `--search`, `--active true|false|all`,\n `--ordering`, `--expand`, `--include`).\n- `project get [id]`: Get a single project by ID (`--expand`, `--include`). Without\n `id`, the project comes from `--project`, then the connection\'s `project`.\n- `task list`: List countermeasures for a project (`--phase`, `--priority`, `--status`,\n `--assigned-to`, `--source`, `--verification`, `--tag`, `--accepted`, `--relevant`,\n `--expand`, `--include`).\n- `task get <task>`: Get a single countermeasure. Pass the composite ID\n from `task list` (`id`, such as `42-T21`); the value goes into the path as one encoded segment,\n with no prefix added, so the bare `task_id` (`T21`) asks for a different path and SD Elements likely answers\n `NOT_FOUND`.\n- `threat list`: List threats for a project (`--severity`, `--search`, `--ordering`,\n `--capec-id`, `--component-id`).\n\nOnly `--active` is checked; every other filter goes to the server as given.\n\n`user list`, `project list`, `task list` and `threat list` page with `--page` (default 1) and\n`--page-size` (default 100), each a positive whole number; `data` is then SD\nElements\' own page, `{ count, next, previous, results }`, with `next` and `previous`\npassed through as the server\'s URLs. `--all` ignores both and fetches every page,\n100 at a time, until `count` is reached or a page comes back empty; `data` is then\none bare list of results. `--all` also stops with an error after 1,000 pages\n(100,000 items), and like every command it\'s subject to toil\'s time limit\n(`TOIL_TIMEOUT_MS`, 120 s by default).\n\nOver MCP the same commands are tools named after the path, with spaces and hyphens\nas underscores (`sde_project_get`, `sde_task_list`), taking camelCase fields named\nafter the arguments and flags (`id`, `task`, `project`, `pageSize`).\n\n```bash\ntoil sde whoami\ntoil sde project list --active true --all\ntoil sde task list --project 42 --phase development --page-size 50\ntoil sde task get 42-T21 --project 42 --expand status,phase\ntoil sde project get 42 --include task_counts\n```\n',
140347
- "skills.md": "---\narea: skills\ndescription: Agent skills from git-hosted marketplaces, installed into the folders Codex, GitHub Copilot and Claude Code read, and switched on and off\n---\n\n# Skills marketplaces (`skills`)\n\nA skills marketplace is a git repository of plugins, each a folder of agent skills\n(`plugins/<plugin>/skills/<skill>/SKILL.md`, optionally listed in\n`.claude-plugin/marketplace.json`). toil clones it, copies plugin skills into the\nskills folder an agent host reads, and switches plugins on and off without deleting\nthem. Verification level: `unit`.\n\n**Supported versions:** git 2.24 or later. toil runs the git already on PATH to clone\nand pull a marketplace, and nothing else. A private marketplace needs git 2.31 or\nlater, which takes its token from the environment rather than the command line;\nan older git gets `GIT_NOT_FOUND` saying so.\n\n## Where skills go\n\n| `--agent` | Project scope (`--scope project`) | User scope (`--scope user`, the default) |\n|-----------|-----------------------------------|------------------------------------------|\n| `codex` (the default) | `.agents/skills` | `~/.agents/skills` |\n| `github-copilot` | `.github/skills` | `~/.copilot/skills` |\n| `claude-code` (`--claude`) | `.claude/skills` | `~/.claude/skills` |\n\n`.agents/skills` is read by Codex and GitHub Copilot alike, which is why it's the\ndefault. Project scope is the root of the repository the workspace is in, or the\nworkspace outside one. `--all-agents` (on `add` and `sync`) installs for all three.\n\nEach skills folder keeps an index, `.toil-installed.json`, recording which skills toil\ninstalled and from where; each installed skill also gets a `toil-origin.json`. A\nswitched-off skill moves to `.toil-disabled/` in the same folder, which agent hosts\ndon't read. toil replaces only skill folders it installed from the same marketplace\nand plugin: a folder of the same name it didn't install is left alone, listed in\n`failed`, with a `SKILLS_NOT_REPLACED` warning. Symlinks in a marketplace are never\ncopied.\n\n## Credential and configuration\n\nEach marketplace is a connection of the `skills` area. `toil skills marketplace add`\nsets one up from a terminal; in CI, define one with env vars.\n\n| Key | Env var (default connection) | Meaning |\n|-----|------------------------------|---------|\n| `repoUrl` | `TOIL_SKILLS_REPO_URL` | Clone URL: `https://\u2026`, or a local path. ssh isn't supported |\n| `localPath` | `TOIL_SKILLS_LOCAL_PATH` | Where the clone lives (default `~/.agents/marketplaces/<repo-name>`) |\n| `branch` | `TOIL_SKILLS_BRANCH` | Branch to clone (default: the remote HEAD) |\n| `username` | `TOIL_SKILLS_USERNAME` | User name sent with the token (default `x-access-token` on GitHub, `x-token-auth` elsewhere; Bitbucket Data Center personal tokens usually need your username) |\n| `provider` | `TOIL_SKILLS_PROVIDER` | `github`, `bitbucket`, `ado` or `git`, when the URL doesn't say |\n| `token` | `TOIL_SKILLS_TOKEN` | HTTP access token for a private marketplace: a secret |\n| `writes` | `TOIL_SKILLS_WRITES` | `true` lets `sync`, `enable` and `disable` change skills folders from this marketplace |\n\nA named connection uses `TOIL_CONN_<NAME>_<KEY>` instead (`TOIL_CONN_CORP_SKILLS_TOKEN`).\nA whole marketplace from env alone:\n\n```bash\nexport TOIL_CONN_CORP_SKILLS_AREA=skills\nexport TOIL_CONN_CORP_SKILLS_REPO_URL=https://bitbucket.imagile.dev/scm/ai/skills.git\nexport TOIL_CONN_CORP_SKILLS_TOKEN=<token>\nexport TOIL_CONN_CORP_SKILLS_WRITES=true\ntoil skills marketplace sync all --marketplace corp-skills --allow-write\n```\n\nThe token lives in the OS credential store (config holds only a `keychain:`\nreference) or an env var, never in the file and never on a command line. Replace it\nwith `toil connections login <name>`. toil hands it to git for that marketplace's\nclone and pull only, as an `http.<url>.extraHeader` in git's environment, which git\nsends to that URL and nowhere else. With no token, git uses your own git credentials.\n\n`--marketplace <name>` picks the marketplace by connection name or clone URL;\nwithout it, the area's default (the first one added), else the only one.\n\n## Writes\n\nInstalling, refreshing and switching plugins changes files on this machine, so `sync`,\n`enable` and `disable` need `\"writes\": true` on the marketplace and `--allow-write` on\nthe call. `add` is CLI only, needs `--allow-write` because it clones, and leaves writes\noff: adding a marketplace never grants installs from it. Turn them on as for any\nconnection: `\"writes\": true` on it in `~/.toil/config.json`, or\n`TOIL_CONN_<NAME>_WRITES=true`. `remove` is CLI only.\n\n## From the menu\n\nBare `toil` on a terminal opens a menu with **Agent skills**, which holds three\nthings: **Skill plugins** (add, update and remove a marketplace, turn its writes on,\ninstall a skill plugin for the agent and place you pick, and tick which skill plugins\nare on; it shows the changes before running them), **View installed skills**, and\n**Install the toil skill** (below). Every screen runs the commands below and prints\neach one, so the menu writes exactly what the command would.\n\n## The toil skill itself\n\nThe skill you're reading ships inside toil. `toil skill install --allow-write` writes it\ninto one agent's folder (`--agent` and `--scope` as above), recorded as `bundled`, and\ntoil keeps it current from then on: `install.md` has the detail. `skills status` lists\nit with `source: \"bundled\"`, and `stale: true` until the next run rewrites a copy\nanother toil version wrote. Marketplace and untracked skills are never rewritten.\n\n## Commands\n\n### `toil skills marketplace add <url> [localPath]`\n\nRegisters a marketplace and clones it, with writes off; it installs nothing. CLI only;\n`setup` is an alias. On a terminal it asks for an access token (leave it empty for a\npublic repository) and keeps it in the OS credential store. The first marketplace\nbecomes the default. Adding it again keeps whatever `writes` you set.\n\n```bash\ntoil skills marketplace add https://bitbucket.imagile.dev/scm/ai/skills.git --name corp-skills --allow-write\n# then set \"writes\": true on corp-skills in ~/.toil/config.json, and:\ntoil skills marketplace sync all --marketplace corp-skills --claude --scope project --allow-write\n```\n\n| Flag | Meaning |\n|------|---------|\n| `--name <name>` | Its connection name (default: from the URL) |\n| `--branch <branch>` | Branch to clone |\n| `--username <username>` | User name sent with the token |\n| `--provider <provider>` | `github`, `bitbucket`, `ado` or `git` |\n\nOutput: `{ name, repoUrl, localPath, branch, tokenConfigured, tokenStorage, provider,\nwrites, cloned, available: [{ name, description }], total, next }`, `next` saying how\nto turn writes on and install.\n\n### `toil skills marketplace list`\n\nEvery registered marketplace: `{ marketplaces: [{ name, repoUrl, localPath,\ntokenConfigured, tokenStorage, provider, username, upstreamRemote, writes }], total }`.\n`tokenStorage` is `keychain`, `env` or `null`; the token itself is never shown. MCP\ntool: `skills_marketplace_list`.\n\n### `toil skills marketplace plugins <name>`\n\nThe plugins a marketplace offers, from its clone: `{ marketplace, plugins: [{ name,\ndescription }], total }`. MCP tool: `skills_marketplace_plugins`.\n\n### `toil skills marketplace sync [plugin]`\n\nClones the marketplace if it isn't yet, otherwise pulls it (fast-forward only), then\ninstalls: one plugin by name, every plugin with `all`, or with no plugin the ones\nalready installed in the target folder. A switched-off plugin stays off; its stashed\ncopy is refreshed. MCP tool: `skills_marketplace_sync`.\n\n```bash\ntoil skills marketplace sync review --allow-write\ntoil skills marketplace sync all --marketplace corp-skills --claude --scope project --allow-write\n```\n\n| Flag | Meaning |\n|------|---------|\n| `--marketplace <name>` | Which marketplace |\n| `--agent <agent>`, `--claude`, `--all-agents` | Which agent hosts |\n| `--scope <scope>` | `user` (default) or `project` |\n| `--installed-only` | With `all`, skip plugins not installed yet |\n\nOutput: `{ marketplace, plugins: { <plugin>: { installed, failed } }, total, target,\nmarketplaceUpdated }`; for one plugin `{ marketplace, plugin, installed, failed, total,\ntarget, marketplaceUpdated }`; for several agents `targets`.\n\n### `toil skills marketplace disable <plugin>`\n\nSwitches a plugin off in one skills folder: its skills move to `.toil-disabled/` and\ntheir records to `disabled` in `.toil-installed.json`. Nothing else in the index\nchanges. MCP tool: `skills_marketplace_disable`.\n\n```bash\ntoil skills marketplace disable review --claude --allow-write\n```\n\nOutput: `{ disabled, alreadyDisabled, skipped, total, target, plugin, stash,\nmarketplace }`.\n\n### `toil skills marketplace enable <plugin>`\n\nSwitches a plugin back on. A skill whose stashed copy has gone is listed in\n`stashMissing`, with a `warning`; `sync <plugin>` restores it. MCP tool:\n`skills_marketplace_enable`.\n\nOutput: `{ enabled, skipped, total, target, plugin, marketplace }`.\n\n`enable` and `disable` take `--marketplace`, `--agent`, `--claude` and `--scope`.\n\n### `toil skills marketplace remove <name>`\n\nUnregisters a marketplace and deletes its token from the OS credential store. Its\nclone and the skills installed from it stay on disk. CLI only.\n\nOutput: `{ removed: { name, repoUrl, localPath }, keychainEntryDeleted, remaining }`.\n\n### `toil skills status`\n\nEvery skill in every agent skills folder, at both scopes: `{ skills: [{ skill, path,\nagent, scope, location, enabled, source, plugin, marketplace, repoUrl, localPath,\nupstreamRemote, branch, installedAt, toilVersion, stale }], total, enabled, disabled,\nuntracked, stale, toilVersion, byMarketplace, locations }`. `source` is `marketplace`,\n`bundled` or `untracked` (a skill toil didn't install). Filter with `--marketplace`,\n`--plugin`, `--source`, `--agent` and `--scope`. MCP tool: `skills_status`.\n\n## Not built yet\n\n`skills list`, `uninstall`,\n`locations`, `guide`, `purge-user`, `marketplace update` (use `toil connections login`\nfor a token), `marketplace instructions`, `marketplace purge-plugin` and\n`marketplace manage` (the welcome menu replaces it). `skills git-auth` is not coming:\ntoil gives git a marketplace's token per call instead of changing your git config.\n",
140450
+ "skills.md": "---\narea: skills\ndescription: Agent skills from git-hosted marketplaces, installed into the folders Codex, GitHub Copilot and Claude Code read, and switched on and off\n---\n\n# Skills marketplaces (`skills`)\n\nA skills marketplace is a git repository of plugins, each a folder of agent skills\n(`plugins/<plugin>/skills/<skill>/SKILL.md`, optionally listed in\n`.claude-plugin/marketplace.json`). toil clones it, copies plugin skills into the\nskills folder an agent host reads, and switches plugins on and off without deleting\nthem. Verification level: `unit`.\n\n**Supported versions:** git 2.24 or later. toil runs the git already on PATH to clone\nand pull a marketplace, and nothing else. A private marketplace needs git 2.31 or\nlater, which takes its token from the environment rather than the command line;\nan older git gets `GIT_NOT_FOUND` saying so.\n\n## Where skills go\n\n| `--agent` | Project scope (`--scope project`) | User scope (`--scope user`, the default) |\n|-----------|-----------------------------------|------------------------------------------|\n| `codex` (the default) | `.agents/skills` | `~/.agents/skills` |\n| `github-copilot` | `.github/skills` | `~/.copilot/skills` |\n| `claude-code` (`--claude`) | `.claude/skills` | `~/.claude/skills` |\n\n`.agents/skills` is read by Codex and GitHub Copilot alike, which is why it's the\ndefault. Project scope is the root of the repository the workspace is in, or the\nworkspace outside one. `--all-agents` (on `add` and `sync`) installs for all three.\n\nEach skills folder keeps an index, `.toil-installed.json`, recording which skills toil\ninstalled and from where; each installed skill also gets a `toil-origin.json`. A\nswitched-off skill moves to `.toil-disabled/` in the same folder, which agent hosts\ndon't read. toil replaces only skill folders it installed from the same marketplace\nand plugin: a folder of the same name it didn't install is left alone, listed in\n`failed`, with a `SKILLS_NOT_REPLACED` warning. Symlinks in a marketplace are never\ncopied.\n\n## Credential and configuration\n\nEach marketplace is a connection of the `skills` area. `toil skills marketplace add`\nsets one up from a terminal; in CI, define one with env vars.\n\n| Key | Env var (default connection) | Meaning |\n|-----|------------------------------|---------|\n| `repoUrl` | `TOIL_SKILLS_REPO_URL` | Clone URL: `https://\u2026`, or a local path. ssh isn't supported |\n| `localPath` | `TOIL_SKILLS_LOCAL_PATH` | Where the clone lives (default `~/.agents/marketplaces/<repo-name>`) |\n| `branch` | `TOIL_SKILLS_BRANCH` | Branch to clone (default: the remote HEAD) |\n| `username` | `TOIL_SKILLS_USERNAME` | User name sent with the token (default `x-access-token` on GitHub, `x-token-auth` elsewhere; Bitbucket Data Center personal tokens usually need your username) |\n| `provider` | `TOIL_SKILLS_PROVIDER` | `github`, `bitbucket`, `ado` or `git`, when the URL doesn't say |\n| `token` | `TOIL_SKILLS_TOKEN` | HTTP access token for a private marketplace: a secret |\n| `writes` | `TOIL_SKILLS_WRITES` | `true` lets `sync`, `enable` and `disable` change skills folders from this marketplace |\n\nA named connection uses `TOIL_CONN_<NAME>_<KEY>` instead (`TOIL_CONN_CORP_SKILLS_TOKEN`).\nA whole marketplace from env alone:\n\n```bash\nexport TOIL_CONN_CORP_SKILLS_AREA=skills\nexport TOIL_CONN_CORP_SKILLS_REPO_URL=https://bitbucket.imagile.dev/scm/ai/skills.git\nexport TOIL_CONN_CORP_SKILLS_TOKEN=<token>\nexport TOIL_CONN_CORP_SKILLS_WRITES=true\ntoil skills marketplace sync all --marketplace corp-skills --allow-write\n```\n\nThe token lives in the OS credential store (config holds only a `keychain:`\nreference) or an env var, never in the file and never on a command line. Replace it\nwith `toil connections login <name>`. toil hands it to git for that marketplace's\nclone and pull only, as an `http.<url>.extraHeader` in git's environment, which git\nsends to that URL and nowhere else. With no token, git uses your own git credentials.\n\n`--marketplace <name>` picks the marketplace by connection name or clone URL;\nwithout it, the area's default (the first one added), else the only one.\n\n## Writes\n\nInstalling, refreshing and switching plugins changes files on this machine, so `sync`,\n`enable` and `disable` need `\"writes\": true` on the marketplace and `--allow-write` on\nthe call. `add` is CLI only, needs `--allow-write` because it clones, and leaves writes\noff: adding a marketplace never grants installs from it. Turn them on as for any\nconnection: `\"writes\": true` on it in `~/.toil/config.json`, or\n`TOIL_CONN_<NAME>_WRITES=true`. `remove` is CLI only.\n\n## From the menu\n\nBare `toil` on a terminal opens a menu with **Agent skills**, which holds three\nthings: **Skill plugins** (add, update and remove a marketplace, turn its writes on,\ninstall a skill plugin for the agent and place you pick, and tick which skill plugins\nare on; it shows the changes before running them), **View installed skills**, and\n**Install the toil skill** (below). Every screen runs the commands below and prints\neach one, so the menu writes exactly what the command would.\n\n## The toil skill itself\n\nThe skill you're reading ships inside toil. `toil skill install --allow-write` writes it\ninto one agent's folder (`--agent` and `--scope` as above), recorded as `bundled`, and\ntoil keeps it current from then on: `install.md` has the detail. `skills status` lists\nit with `source: \"bundled\"`, and `stale: true` until the next run rewrites a copy\nanother toil version wrote. Marketplace and untracked skills are never rewritten.\n\n## Commands\n\n### `toil skills marketplace add <url> [localPath]`\n\nRegisters a marketplace and clones it, with writes off; it installs nothing. CLI only;\n`setup` is an alias. On a terminal it asks for an access token (leave it empty for a\npublic repository, or to keep the one already stored), checks the paste as\n`connections add` does (`core.md`), and keeps it in the OS credential store. The first marketplace\nbecomes the default. Adding it again keeps whatever `writes` you set.\n\n```bash\ntoil skills marketplace add https://bitbucket.imagile.dev/scm/ai/skills.git --name corp-skills --allow-write\n# then set \"writes\": true on corp-skills in ~/.toil/config.json, and:\ntoil skills marketplace sync all --marketplace corp-skills --claude --scope project --allow-write\n```\n\n| Flag | Meaning |\n|------|---------|\n| `--name <name>` | Its connection name (default: from the URL) |\n| `--branch <branch>` | Branch to clone |\n| `--username <username>` | User name sent with the token |\n| `--provider <provider>` | `github`, `bitbucket`, `ado` or `git` |\n\nOutput: `{ name, repoUrl, localPath, branch, tokenConfigured, tokenStorage, provider,\nwrites, cloned, available: [{ name, description }], total, next }`, `next` saying how\nto turn writes on and install.\n\n### `toil skills marketplace list`\n\nEvery registered marketplace: `{ marketplaces: [{ name, repoUrl, localPath,\ntokenConfigured, tokenStorage, provider, username, upstreamRemote, writes }], total }`.\n`tokenStorage` is `keychain`, `env` or `null`; the token itself is never shown. MCP\ntool: `skills_marketplace_list`.\n\n### `toil skills marketplace plugins <name>`\n\nThe plugins a marketplace offers, from its clone: `{ marketplace, plugins: [{ name,\ndescription }], total }`. MCP tool: `skills_marketplace_plugins`.\n\n### `toil skills marketplace sync [plugin]`\n\nClones the marketplace if it isn't yet, otherwise pulls it (fast-forward only), then\ninstalls: one plugin by name, every plugin with `all`, or with no plugin the ones\nalready installed in the target folder. A switched-off plugin stays off; its stashed\ncopy is refreshed. MCP tool: `skills_marketplace_sync`.\n\n```bash\ntoil skills marketplace sync review --allow-write\ntoil skills marketplace sync all --marketplace corp-skills --claude --scope project --allow-write\n```\n\n| Flag | Meaning |\n|------|---------|\n| `--marketplace <name>` | Which marketplace |\n| `--agent <agent>`, `--claude`, `--all-agents` | Which agent hosts |\n| `--scope <scope>` | `user` (default) or `project` |\n| `--installed-only` | With `all`, skip plugins not installed yet |\n\nOutput: `{ marketplace, plugins: { <plugin>: { installed, failed } }, total, target,\nmarketplaceUpdated }`; for one plugin `{ marketplace, plugin, installed, failed, total,\ntarget, marketplaceUpdated }`; for several agents `targets`.\n\n### `toil skills marketplace disable <plugin>`\n\nSwitches a plugin off in one skills folder: its skills move to `.toil-disabled/` and\ntheir records to `disabled` in `.toil-installed.json`. Nothing else in the index\nchanges. MCP tool: `skills_marketplace_disable`.\n\n```bash\ntoil skills marketplace disable review --claude --allow-write\n```\n\nOutput: `{ disabled, alreadyDisabled, skipped, total, target, plugin, stash,\nmarketplace }`.\n\n### `toil skills marketplace enable <plugin>`\n\nSwitches a plugin back on. A skill whose stashed copy has gone is listed in\n`stashMissing`, with a `warning`; `sync <plugin>` restores it. MCP tool:\n`skills_marketplace_enable`.\n\nOutput: `{ enabled, skipped, total, target, plugin, marketplace }`.\n\n`enable` and `disable` take `--marketplace`, `--agent`, `--claude` and `--scope`.\n\n### `toil skills marketplace remove <name>`\n\nUnregisters a marketplace and deletes its token from the OS credential store. Its\nclone and the skills installed from it stay on disk. CLI only.\n\nOutput: `{ removed: { name, repoUrl, localPath }, keychainEntryDeleted, remaining }`.\n\n### `toil skills status`\n\nEvery skill in every agent skills folder, at both scopes: `{ skills: [{ skill, path,\nagent, scope, location, enabled, source, plugin, marketplace, repoUrl, localPath,\nupstreamRemote, branch, installedAt, toilVersion, stale }], total, enabled, disabled,\nuntracked, stale, toilVersion, byMarketplace, locations }`. `source` is `marketplace`,\n`bundled` or `untracked` (a skill toil didn't install). Filter with `--marketplace`,\n`--plugin`, `--source`, `--agent` and `--scope`. MCP tool: `skills_status`.\n\n## Not built yet\n\n`skills list`, `uninstall`,\n`locations`, `guide`, `purge-user`, `marketplace update` (use `toil connections login`\nfor a token), `marketplace instructions`, `marketplace purge-plugin` and\n`marketplace manage` (the welcome menu replaces it). `skills git-auth` is not coming:\ntoil gives git a marketplace's token per call instead of changing your git config.\n",
140348
140451
  "sonar.md": '---\narea: sonar\ndescription: Quality gate status, issues, security hotspots, measures and projects on SonarQube Server\n---\n\n# SonarQube Server (`sonar`)\n\nQuality gate status, issues, security hotspots, measures and projects on\n**SonarQube Server**, through its Web API (`/api/...`). Every command reads; none\nchanges anything. Verification level: `unit`.\n\n**Supported versions:** The oldest SonarQube Server version toil supports hasn\'t been established. toil\ncalls the unversioned Web API with a user token sent as a Bearer header. No release\nhas been verified yet.\n\n## Credential\n\nA SonarQube **user token**: in SonarQube, My Account \u2192 Security \u2192 Generate Tokens.\ntoil sends it as `Authorization: Bearer <token>`. There is no username, password or\nbrowser login.\n\n## Configuration\n\n| Key | Env var | Required | Meaning |\n|-----|---------|----------|---------|\n| `baseUrl` | `TOIL_SONAR_BASE_URL` | yes | SonarQube server root, e.g. `https://sonar.imagile.dev` (keep any context path) |\n| `token` | `TOIL_SONAR_TOKEN`, then `SONAR_TOKEN` | yes | User token |\n| `project` | `TOIL_SONAR_PROJECT` | no | Default project key for `quality-gate get`, `issue list`, `measure list` and `hotspot list` |\n\n**CI fallback:** when `TOIL_SONAR_TOKEN` isn\'t set, the default connection takes its\ntoken from `SONAR_TOKEN`, the variable SonarSource\'s own scanner reads. It sits\ndirectly below `TOIL_SONAR_TOKEN` and above the config file. There\'s no fallback for\nthe base URL.\n\nEnvironment variables (CI, or a one-off shell):\n\n```bash\nexport TOIL_SONAR_BASE_URL=https://sonar.imagile.dev\nexport TOIL_SONAR_TOKEN=<your user token>\n```\n\nOr `~/.toil/config.json`, with `project` usually set once under `defaults.sonar`:\n\n```json\n{\n "version": 2,\n "connections": {\n "corp-sonar": { "area": "sonar", "baseUrl": "https://sonar.imagile.dev" }\n },\n "defaults": { "sonar": { "connection": "corp-sonar", "project": "imagile-api" } }\n}\n```\n\nThe token never goes in this file; a plaintext one there is refused with\n`CONFIG_INVALID`. Run `toil connections add corp-sonar --area sonar` (or\n`toil connections login corp-sonar` for an existing connection) to keep it in the OS\ncredential store, or set `TOIL_SONAR_TOKEN`.\n\n## Commands\n\nThe project comes from `--project <key>`, else the connection\'s `project` (usually\n`defaults.sonar.project`). With neither, the command fails with "No project\nspecified".\n\n- `quality-gate get`: Get quality gate status for a project (`--branch`).\n- `issue list`: Search/list issues for a project. Filters `--severities`, `--types` and\n `--statuses` take comma lists; `--resolved` sends `true` only for the exact string\n `true`, anything else as `false`.\n- `measure list`: Get key metrics for a project. `--metrics` defaults to coverage,\n duplicated lines density, bugs, vulnerabilities, code smells, the three ratings\n and ncloc.\n- `project list`: Search/list projects (`--query`). SonarQube\'s `api/projects/search`\n needs the Administer System permission, so other tokens may get `AUTH`.\n- `hotspot list`: List security hotspots for a project (`--status`, `--resolution`).\n- `check-dossier`: Check that every project key the call\'s dossier names (`project`,\n `projectKeys`, `projects`) exists, through `api/components/show`. Returns `{ dossier,\n connection, env, ok, checked, checks, unchecked }`, and the CLI exits 1 when one is missing.\n\n`issue list`, `project list` and `hotspot list` page with `--page` (default 1) and `--page-size`\n(default 100), passed to the server as given; `data` is then SonarQube\'s own page.\n`--all` ignores both and fetches every page, 500 at a time, until the total is\nreached or a page comes back empty; `data` is then one flat list of items. SonarQube refuses `issue list` past the\n10,000th result, so `issue list --all` on a larger result fails; narrow the filters.\n`--all` also stops with an error after 1,000 pages (500,000 items), and like every\ncommand it\'s subject to toil\'s time limit (`TOIL_TIMEOUT_MS`, 120 s by default), so a\nvery large `project list` or `hotspot list --all` can end in `TIMEOUT`.\n\nOver MCP the same commands are tools named after the path, with spaces and hyphens\nas underscores (`sonar_issue_list`, `sonar_quality_gate_get`), taking camelCase\nfields named after the flags (`project`, `pageSize`).\n\n```bash\ntoil sonar quality-gate get --project imagile-api\ntoil sonar issue list --project imagile-api --severities BLOCKER,CRITICAL --all\ntoil sonar measure list --metrics coverage,bugs --branch main\n```\n',
140349
140452
  "sonatypeiq.md": '---\narea: sonatypeiq\ndescription: Applications, organizations, policies and policy evaluations on Sonatype IQ Server\n---\n\n# Sonatype IQ Server (`sonatypeiq`)\n\nApplications, organizations and policies on **Sonatype IQ Server**, read through its\nREST API (`/api/v2/...`), and a policy evaluation of a dependency inventory against\none application. Nothing here changes anything in IQ Server. Verification level:\n`unit`.\n\n**Supported versions:** The oldest Sonatype IQ Server version toil supports hasn\'t been established. toil\ncalls only `/api/v2` endpoints, with a user token pair sent as HTTP Basic. No release\nhas been verified yet.\n\n## Credential\n\nAn IQ Server **user token**: in IQ Server, open your profile and choose User Token,\nthen create one. It has two halves, a user code and a passcode. toil sends them as\n`Authorization: Basic base64(userCode:passcode)`. It is not your login password, and\nthere is no browser login.\n\n## Configuration\n\n| Key | Env var | Required | Meaning |\n|-----|---------|----------|---------|\n| `baseUrl` | `TOIL_SONATYPEIQ_BASE_URL` | yes | Sonatype IQ Server root, e.g. `https://iq.imagile.dev` (keep any context path) |\n| `userCode` | `TOIL_SONATYPEIQ_USER_CODE` | yes | User token code |\n| `passcode` | `TOIL_SONATYPEIQ_PASSCODE` | yes | User token passcode (a secret) |\n\nThere\'s no CI fallback variable.\n\nEnvironment variables (CI, or a one-off shell):\n\n```bash\nexport TOIL_SONATYPEIQ_BASE_URL=https://iq.imagile.dev\nexport TOIL_SONATYPEIQ_USER_CODE=<your user code>\nexport TOIL_SONATYPEIQ_PASSCODE=<your passcode>\n```\n\nOr `~/.toil/config.json`:\n\n```json\n{\n "version": 2,\n "connections": {\n "corp-iq": { "area": "sonatypeiq", "baseUrl": "https://iq.imagile.dev", "userCode": "abc12345" }\n },\n "defaults": { "sonatypeiq": { "connection": "corp-iq" } }\n}\n```\n\nThe passcode never goes in this file; a plaintext one there is refused with\n`CONFIG_INVALID`. Run `toil connections add corp-iq --area sonatypeiq` (or\n`toil connections login corp-iq` for an existing connection) to keep it in the OS\ncredential store, or set `TOIL_SONATYPEIQ_PASSCODE`.\n\n## Commands\n\nThe four read commands return IQ Server\'s answer unchanged as `data`.\n\n- `application list`: List all applications in Sonatype IQ Server\n (`--organization-id <id>`, sent as an `organizationId` query parameter, which IQ\n may ignore).\n- `application get <public-id>`: Get an application by its public ID. `data`\n is the filtered list, `{ applications: [...] }`; an unknown ID gives an empty\n list, not an error.\n- `organization list`: List all organizations in Sonatype IQ Server.\n- `policy list`: List all policies (`--organization-id <id>` asks\n `/api/v2/policies/organization/<id>`).\n- `evaluate --application-id <id>` (also `toil deps frisk --source\n sonatypeiq`): Evaluate a dependency inventory against an application\'s policies.\n `--application-id` is the application\'s public ID. `data` is `{ tier, source, sourcesQueried,\n sourceErrors, scanned, vulnerable, packages }`, each package with its\n `vulnerabilities`.\n\n`evaluate` reads the inventory that `toil deps scan` writes, from `--from <file>` or,\nwhen that\'s left out on the CLI, from piped stdin (with nothing piped in on a terminal it\nrefuses at once rather than wait); over MCP, pass `from`. Use `deps scan\n--include-transitive` to evaluate transitive dependencies too. `--ecosystem\nnpm|nuget|maven|all` (default `all`), `--direct-only` and `--include-dev` filter the\ninventory first. `toil deps frisk --source sonatypeiq` takes the same flags and runs\nthis command.\n\nIt looks up the application\'s internal ID by public ID (if the lookup fails or finds\nnothing, the public ID is used as it is), then posts the packages as package URLs,\n128 at a time. If IQ answers that the evaluation is queued, toil polls the\n`resultsUrl` up to 10 times, waiting 2 s longer each time, and fails if it\'s still\nqueued. A `resultsUrl` on another host is fetched from the connection\'s host\ninstead, with a `SONATYPEIQ_RESULTS_HOST` warning. Only `SECURITY` policy violations\ncount, with threat level 9 or more as `CRITICAL`, 7 `HIGH`, 4 `MEDIUM` and above 0\n`LOW`. The command is allowed up to 600 s.\n\n`meta.warnings` says `SONATYPEIQ_NO_COMPONENTS` when IQ\'s answer had no\n`components` list to read findings from, and `SONATYPEIQ_UNMATCHED_RESULT` for a\nresult that matches no package sent. Either means the result may undercount.\n\nOver MCP the same commands are tools named after the path, with spaces as\nunderscores (`sonatypeiq_application_list`, `sonatypeiq_evaluate`),\ntaking camelCase fields (`publicId`, `applicationId`, `organizationId`, `from`).\n\n```bash\ntoil sonatypeiq application list\ntoil sonatypeiq application get imagile-api\ntoil deps scan --include-transitive | toil sonatypeiq evaluate --application-id imagile-api\ntoil sonatypeiq evaluate --application-id imagile-api --from inventory.json --ecosystem npm\n```\n',
140350
140453
  "splitio.md": '---\narea: splitio\ndescription: Split.IO feature flags, environments and change requests through the Split Admin API\n---\n\n# Split.IO (`splitio`)\n\nFeature flags, environments and change requests on **Split.IO** (Harness FME),\nthrough the Admin API under `/internal/api/v2`. The reads list workspaces,\nenvironments, flags and change requests; every write files a **change request**\nthat Split\'s approvers then accept or reject. toil never changes a flag directly.\nVerification level: `unit`.\n\n**Supported versions:** The oldest Split.IO Admin API version toil supports hasn\'t been established. toil calls the\nAdmin API under `/internal/api/v2` with an Admin API key sent as a Bearer header. It\nhas not been run against a live Split account yet.\n\n## Credential\n\nA Split **Admin API key**: in Split, Admin settings \u2192 API keys \u2192 Create API key, with\nthe type Admin. toil sends it as `Authorization: Bearer <key>`. There is no login and\nno token exchange.\n\n## Configuration\n\n| Key | Env var | Required | Meaning |\n|-----|---------|----------|---------|\n| `baseUrl` | `TOIL_SPLITIO_BASE_URL` | yes | Admin API root, normally `https://api.split.io` |\n| `adminApiKey` | `TOIL_SPLITIO_ADMIN_API_KEY` | yes | Admin API key |\n| `workspace` | `TOIL_SPLITIO_WORKSPACE` | no | Default Split workspace (project) ID, used when `--ws` is not given |\n\nThere is no CI fallback variable.\n\n```bash\nexport TOIL_SPLITIO_BASE_URL=https://api.split.io\nexport TOIL_SPLITIO_ADMIN_API_KEY=<your Admin API key>\n```\n\nOr `~/.toil/config.json`:\n\n```json\n{\n "version": 2,\n "connections": {\n "split": { "area": "splitio", "baseUrl": "https://api.split.io", "workspace": "<workspace id>" }\n }\n}\n```\n\nThe key never goes in this file; a plaintext one there is refused with\n`CONFIG_INVALID`. Run `toil connections add split --area splitio` to keep it in the\nOS credential store, or set `TOIL_SPLITIO_ADMIN_API_KEY`.\n\n## The workspace is `--ws`\n\nEvery command but `workspace list` and `change-request get` acts in one Split\nworkspace: `--ws <id>`, else the connection\'s `workspace`. Over MCP the field is\n`workspace`. **On the CLI, `--workspace` is toil\'s own flag** for the folder commands\nmay read files in, so `--workspace <split id>` doesn\'t name the Split workspace; a\ncommand left without one fails with `INVALID_INPUT` saying to pass `--ws`.\n\n## Commands\n\nReads:\n\n- `workspace list`: List all Split.IO workspaces, every page.\n- `environment list`: List environments in a workspace.\n- `flag list`: List feature flags in a workspace. `--limit` (default 50, Split\'s\n maximum) and `--offset` (default 0); `data.totalCount` is Split\'s total.\n `--flag-set` is sent as `flagSetName`, which Split\'s reference doesn\'t document,\n so the result carries a warning to compare `totalCount` with an unfiltered list.\n- `flag get <flag>`: Get a flag, or with `--environment` its definition in that\n environment: treatments, rules, default rule, kill state.\n- `change-request list`: List Change Requests for a workspace (`--environment`,\n `--status`; Split returns `REQUESTED` ones when `--status` is unset). `--limit`\n defaults to 25 (Split allows 1 to 100). Split pages by marker: pass\n `data.nextMarker` (also `meta.page.nextCursor`) as `--after` for the next page.\n `--offset` accepts only 0, and `totalCount` is `null`, since Split reports none.\n- `change-request get <id>`: Get a Change Request by ID.\n\nWrites, each a change request against one `--environment`. They need `writes: true`\non the connection and `--allow-write` on the call. Every one takes `--mnemonic` (the\ntitle), `--description` (the comment), `--change-number` (added to the comment as\n"Change number: \u2026", since Split has no field for it), `--approvers` (comma-separated\nemail addresses, only where the environment lets submitters choose) and\n`--rollout-status <id>` (a rollout status ID; Split\'s guide says KILL doesn\'t need\none, and the others may).\n\n- `flag update <flag>`: Replace a flag\'s definition with the JSON object in `--input-file`\n (`-` reads stdin on the CLI). Start from `flag get <flag> --environment`.\n- `flag set-rule <flag>`: Change rule `--rule-index` (from 0) to one `--treatment` (a\n 100% bucket) or `--weights` (a JSON array of `{treatment, size}`, sizes in percent;\n anything but an array is refused).\n The rest of the definition is copied from the current one.\n- `flag set-default <flag>`: Set the default rule to one `--treatment` at 100%.\n- `flag toggle <flag>`: `--enabled false` (or `0`) kills the flag; **any other value\n restores it**, `off` and `no` included. A value other than `true` or `1` that\n restores adds a `SPLITIO_TOGGLE_RESTORED` warning to `meta.warnings` saying so.\n- `flag toggle-many`: One change request per entry of `--input-file`, a JSON array\n of `{flag, enabled}`, titled `<mnemonic> \u2014 <flag>`. A failed entry doesn\'t stop the\n rest; it\'s reported in `results[]` with `ok: false`, the envelope stays `ok`, and\n `meta.warnings` says how many failed. `enabled` is read by truthiness, so the\n string `"false"` restores. Every entry must have a `flag` name; if one doesn\'t, the\n command fails with `INVALID_INPUT` naming the entry, before any request is filed.\n- `flag kill <flag>`, `flag restore <flag>`: Kill or restore a flag in the environment.\n- `flag archive <flag>`: Remove a flag\'s definition from the environment (Split\'s\n `ARCHIVE` change request; not Split\'s flag-archive API). CLI only: it removes a\n definition, and deletes are never served over MCP.\n\n```bash\ntoil splitio workspace list\ntoil splitio flag get new_checkout --ws <workspace id> --environment <environment id>\ntoil splitio flag kill new_checkout --ws <workspace id> --environment <environment id> \\\n --mnemonic checkout-off --description "Kill during incident" --change-number CHG0001234 --allow-write\n```\n',
140351
- "util.md": '---\narea: util\ndescription: Local utilities with no connection or network, decoding a JWT, inventorying dependencies from manifests and lockfiles, checked encoding and hashing, decoding certificates and checking a chain, summarising test, SARIF and coverage reports, triaging a large log, scanning for secrets before a commit or post, sizing files and folders before reading them, time zone, duration, business-day and cron arithmetic, comparing versions and ranges for npm, NuGet and Maven, converting Markdown to and from Jira and Confluence formats, reading OpenAPI documents, drawing C4 architecture diagrams from a JSON model, mapping Jira, Azure DevOps and GitHub work items to Open Work Items, and finding likely duplicates among them\n---\n\n# Local utilities (`util`)\n\nCommands that work on what\'s on this machine: a token or version you paste, a file or\nfolder in the workspace (a certificate, a log or an API description), the manifests and lockfiles there, a\nreport a build left behind, a C4 model described in JSON, text you\'re about to commit or post, or a time and a time zone. They aren\'t\nintegrations. There is no server, no connection to add, no `TOIL_UTIL_*`\nvariable, no credential and no `--connection` flag, and none of them sends\nanything over the network. None changes anything: the only file one writes is a\nnew one you name with `--out`, inside the workspace, and it never replaces a\nfile. Verification level: `unit`.\n\n`jwt` and `deps` also have a short path, an alias that does the same thing with\nthe same flags and output:\n\n| Command | Alias | MCP tool |\n|---------|-------|----------|\n| `toil util jwt decode` | `toil jwt decode` | `util_jwt_decode` |\n| `toil util deps scan` | `toil deps scan` | `util_deps_scan` |\n| `toil util deps diff` | `toil deps diff` | `util_deps_diff` |\n| `toil util secrets scan` | none | `util_secrets_scan` |\n| `toil util encode` | none | `util_encode` |\n| `toil util cert` | none | `util_cert` |\n| `toil util report` | none | `util_report` |\n| `toil util log` | none | `util_log` |\n| `toil util size` | none | `util_size` |\n| `toil util time convert` | none | `util_time_convert` |\n| `toil util time duration` | none | `util_time_duration` |\n| `toil util time business-days add` | none | `util_time_business_days_add` |\n| `toil util time business-days diff` | none | `util_time_business_days_diff` |\n| `toil util time cron` | none | `util_time_cron` |\n| `toil util semver compare` | none | `util_semver_compare` |\n| `toil util semver satisfies` | none | `util_semver_satisfies` |\n| `toil util semver sort` | none | `util_semver_sort` |\n| `toil util semver bump` | none | `util_semver_bump` |\n| `toil util md` | none | `util_md` |\n| `toil util openapi list` | none | `util_openapi_list` |\n| `toil util openapi show` | none | `util_openapi_show` |\n| `toil util openapi example` | none | `util_openapi_example` |\n| `toil util c4 render` | none | `util_c4_render` |\n| `toil util c4 mermaid` | none | `util_c4_mermaid` |\n| `toil util c4 d2` | none | `util_c4_d2` |\n| `toil util owi map` | none | `util_owi_map` |\n| `toil util owi similar` | none | `util_owi_similar` |\n\nOver MCP the tools are served without any configuration. `toil mcp --areas util`\nserves just these.\n\n## By job\n\nThe same commands, grouped by what you need them for.\n\n### Reading CI output\n\nWhat a build or a scanner leaves behind, turned into something short enough to read: totals and failures from a report, and the errors that matter from a log thousands of lines long.\n\n- **Summarising a report** (`toil util report`): Turns what CI and scanners write into one JSON summary. JUnit XML (Maven Surefire, Jenkins and Azure DevOps shapes) and TRX become test totals plus each failure with its suite, name, file, line, message and the first lines of its stack. SARIF 2.1.0 becomes findings with rule, level, file and line. lcov and Cobertura become per-file line and branch percentages and the lowest-covered files.\n- **Triaging a log** (`toil util log`): Reads a CI console, a Maven, npm or dotnet build, or a test run, and returns what\'s worth reading: the error and warning lines grouped by signature, with numbers, ids, timestamps and hex replaced so the same complaint counts once. Each group has its count, its first and last line, one sample, and the Java, .NET, Node or Python stack trace that belongs to it.\n\n### Writing for the tools\n\nGetting text into the shape an enterprise tool expects before it\'s sent, so a description, a page or a request arrives the way it was meant.\n\n- **Converting Markdown** (`toil util md`): Turns Markdown into Jira wiki markup (Jira Data Center), Atlassian Document Format (Jira Cloud and Confluence Cloud) or Confluence storage format (Confluence Data Center), and any of those back into Markdown.\n- **Reading an OpenAPI document** (`toil util openapi list`, `toil util openapi show`, `toil util openapi example`): Reads an OpenAPI 3.0, 3.1 or 3.2 or Swagger 2.0 document, so an agent calls an endpoint right the first time: `list` gives every operation, `show` lays one out with each parameter and where it goes, its request and response bodies with `$ref`s expanded, and the exact inputs for `toil <area> api`, and `example` builds the smallest body its schema accepts.\n- **Drawing a C4 architecture diagram** (`toil util c4 render`, `toil util c4 mermaid`, `toil util c4 d2`): Draws one view of a C4 model (a system context, container or component view) from JSON an agent writes: `render` lays it out and returns SVG, people on top and the scope\'s children inside a dashed boundary, checked for overlaps, arrows behind boxes and well-formed XML, and `mermaid` and `d2` write the same view as text for places that draw it themselves, such as a Mermaid block in Markdown on GitHub.\n\n### Reading the trackers as one\n\nWork from Jira, Azure DevOps and GitHub in one shape, so a sprint, a board or a question about the work reads the same whichever tracker holds it.\n\n- **Mapping to Open Work Items** (`toil util owi map`): Turns what the jira, jira-cloud, ado, ado-cloud and github commands print into Open Work Items: one model with a type, a status and its category, people, an estimate with its unit and the field it came from, the sprint, parent and children, links, dates and the history of transitions and sprint moves. A GitHub issue and its project board item become one item. The pull requests of github, bitbucket, bitbucket-cloud, ado and ado-cloud become changes: state, who wrote it (a person, an agent or a bot, and the signal that said so), reviewers, checks, size, the work items it names and its review timeline. Every record is checked against the published schema.\n- **Finding likely duplicates** (`toil util owi similar`): Before filing, proposing or triaging an item, asks whether it already exists: ranks OWI records against some text or one of them, or lists likely duplicate pairs across Jira, Azure DevOps and GitHub. Lexical and deterministic, with no model or network, and every match says why it matched: the shared title and body terms, title trigrams, labels, parent and link.\n\n### Safety\n\nChecks to run before something leaves the machine or gets trusted: a secret in a diff, a certificate chain that won\'t validate, a token\'s claims, and the dependencies a repository ships.\n\n- **Scanning for secrets** (`toil util secrets scan`): Looks for credential-shaped strings before you commit, push or post them: tokens, keys, `password=` values, credentials in URLs, private keys and long random strings. It uses the same rules toil\'s audit log redacts with, plus an entropy check, and exits with 1 when it finds anything, so a hook or a pipeline can stop on it.\n- **Decoding certificates** (`toil util cert`): Decodes a certificate or a chain bundle, PEM or DER: subject, issuer, SANs, serial, how many days it has left, its key, its signature algorithm, its basic constraints and key usage, and its fingerprints, so a TLS failure can be explained from the files. It never connects to the host.\n- **Decoding a JWT** (`toil util jwt decode`): Shows a token\'s header and claims, so you can see who it\'s for, what it grants and when it expires.\n- **Inventorying dependencies** (`toil util deps scan`, `toil util deps diff`): `deps scan` lists every package the workspace\'s npm, NuGet and Maven/Gradle manifests and lockfiles declare, with its version, the file it came from, and whether it\'s direct or transitive, production or dev. That inventory is what the vulnerability and licence commands read, one source per command, so you choose which service sees your dependency list. `deps diff` lists what was added, removed, upgraded or downgraded between two git refs.\n\n### Arithmetic models get wrong\n\nWork that looks simple and is easy to get subtly wrong by reasoning alone: time zones and DST, version ordering, encodings and hashes, and how big a file is before reading it. Each one works the answer out, then checks it a second way.\n\n- **Time zones, durations, business days and cron** (`toil util time convert`, `toil util time duration`, `toil util time business-days add`, `toil util time business-days diff`, `toil util time cron`): Date arithmetic on the time zone data Node already ships: convert a time between zones, read or write an ISO 8601 duration, add or count business days, and list a cron schedule\'s next run times.\n- **Comparing versions** (`toil util semver compare`, `toil util semver satisfies`, `toil util semver sort`, `toil util semver bump`): Compare, sort and bump versions, and check them against ranges, in the grammar of the ecosystem they come from: npm (SemVer 2.0.0 and npm\'s ranges, the default), NuGet (up to four parts, interval notation) or Maven (Maven\'s own ordering, where `1.0.0.Final` is `1` and `SNAPSHOT` comes before the release).\n- **Encoding, decoding and hashing** (`toil util encode`): Base64, base64url, hex, URL components and form values, in either direction, and a file\'s SHA-256, SHA-1 or MD5 hash.\n- **Sizing before reading** (`toil util size`): Tells an agent how much a file or folder will cost to read. For a file it gives bytes, lines, an estimated token count, and an outline: functions, classes and methods with their line ranges for TypeScript, JavaScript, Python, C#, Java and Go, headings for Markdown, and top-level keys for JSON and YAML, so the agent reads only the lines it needs. For a folder it gives a tree of totals, largest first, and names the largest files.\n\n## Commands\n\n### `toil util jwt decode`\n\nDecodes a JWT\'s header and claims **without verifying it**. There\'s no key and no\nnetwork call, and nothing here says whether the token is valid, expired or trusted.\n\n```bash\ntoil util jwt decode eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJhYmMxMjM0NSJ9.c2ln\necho "$TOKEN" | toil util jwt decode -\n```\n\n| Argument | Meaning |\n|----------|---------|\n| `<token>` | The token, `header.payload.signature`. `-` reads it from stdin, which keeps it out of the process list and your shell history; one trailing line ending is dropped |\n\nOutput: `{ header, payload, signature }`, the header and claims as parsed JSON and\nthe signature segment as the text it is.\n\n- A token that isn\'t three dot-separated parts (an encrypted 5-part JWE, say) fails\n with `INVALID_INPUT`, `Invalid JWT: expected 3 dot-separated parts`.\n- A header or payload that doesn\'t decode to JSON fails with `Invalid JWT: header is\n not valid JSON` (or `payload`). A `Bearer ` prefix gives this error too, so strip it.\n- The decoding is lenient, as it has always been. A segment that is JSON but not an\n object (`null`, a number) comes back as it is. Characters outside base64url are\n skipped. Invalid UTF-8 shows as `\uFFFD`. Whitespace in a token passed as an argument\n is kept, so a trailing newline ends up in `signature`.\n\nThe token goes nowhere but the decoder. toil doesn\'t log it, and no error message\nrepeats it.\n\n### `toil util deps scan`\n\nThe dependency inventory of the workspace, from its manifests and lockfiles. It\nreads files only and needs no git. It must be inside a git repository, though, or it\nfails with `Not inside a git repository. deps commands require a git repo root.`\n\n```bash\ntoil util deps scan\ntoil util deps scan --ecosystem npm --include-transitive --include-dev\ntoil util deps scan | toil osv vulns\n```\n\n| Flag | Meaning |\n|------|---------|\n| `--ecosystem <ecosystem>` | `npm`, `nuget`, `maven` or `all` (default). Any other value matches nothing and scans nothing |\n| `--include-transitive` | Include transitive dependencies (left out by default) |\n| `--include-dev` | Include dev and test dependencies (left out by default) |\n\nWhich files it reads:\n\n- **Which files:** every file in the workspace that `git ls-files --cached --others\n --exclude-standard` would list. That\'s tracked files plus untracked ones `.gitignore`\n and `.git/info/exclude` don\'t cover. A nested repository isn\'t walked into. Your\n global git excludes file isn\'t read, so a file only it ignores is scanned. An\n ignore file that exists but can\'t be read applies no rules, with a\n `GITIGNORE_UNREADABLE` warning naming it and the fix.\n- **npm:** `package.json` (not under `node_modules`), with the first of\n `package-lock.json` (v2 or later), `yarn.lock` (v1) or `pnpm-lock.yaml` beside it.\n A `package-lock.json` with no packages falls back to `package.json`.\n- **NuGet:** `.csproj`, `.fsproj`, `.vbproj`, `packages.config` and\n `Directory.Packages.props`, with a `packages.lock.json` in the same folder. Project\n files that share one lock file count once. A project with no version on a\n `PackageReference` takes it from the nearest `Directory.Packages.props`, up to 10\n folders up.\n- **Maven/Gradle:** `pom.xml`, `build.gradle` and `build.gradle.kts`, with a\n `gradle.lockfile` beside them.\n\nA lockfile wins over its manifest. Packages are de-duplicated on ecosystem, name,\nversion and source file. A manifest that can\'t be read is skipped. One that exists\nbut can\'t be read (a link out of the workspace, say) also gets a\n`DEPS_FILE_SKIPPED` warning in `meta.warnings`. That warning is the only check it\nmakes of its own result: the `deps` commands have no `verified` block, so treat the\nquirks below as unchecked.\n\nOutput:\n\n```json\n{\n "ecosystems": ["npm", "nuget", "maven"],\n "manifests": [{ "file": "package.json", "ecosystem": "npm", "lockFile": "package-lock.json" }],\n "packages": [{ "name": "lodash", "version": "4.17.21", "ecosystem": "npm", "source": "package-lock.json", "type": "direct", "scope": "production" }],\n "summary": { "totalPackages": 1, "byEcosystem": { "npm": 1 }, "byType": { "direct": 1, "transitive": 0 }, "byScope": { "production": 1, "dev": 0 } }\n}\n```\n\nPaths are relative to the workspace, with forward slashes. Maven names are\n`group:artifact`. When the repository\'s root is above the workspace, only the\nworkspace is scanned: run it from the root, or pass `--workspace <root>`, to scan\neverything.\n\nKnown quirks, which stay until they\'re checked against real repositories:\n\n- In an npm v7+ lockfile, `direct` means hoisted to the top `node_modules`, so most\n transitive packages count as direct. Workspace folders show up as packages.\n- Yarn 1 headers with several ranges give a garbled name. Yarn 2+ lockfiles give no\n packages.\n- pnpm peer suffixes stay in the version, and pnpm 9\'s scoped packages are missed.\n- `CentralTransitive` NuGet packages count as direct.\n- `gradle.lockfile` test dependencies are always included.\n- Any `word \'a:b:c\'` string in `build.gradle` reads as a dependency.\n- `pom.xml` plugin dependencies count as the project\'s.\n\nThe output is the inventory the vulnerability and licence commands read from stdin\nor `--from <file>`: `toil osv vulns`, `toil ossindex vulns`, `toil sonatypeiq\nevaluate`, and `toil artifactory package outdated` / `license-check`. Over MCP, save it to a\nfile in the workspace and pass that file\'s path as `from`.\n\n### `toil util deps diff`\n\nHow the inventory changed between two git refs. This command runs the git on PATH:\n`git ls-tree` for each ref\'s files and `git show` for each one it reads. Without git\nit fails with `GIT_NOT_FOUND`.\n\n```bash\ntoil util deps diff --from main\ntoil util deps diff --from v1.0.0 --to main --ecosystem npm --include-dev\n```\n\n| Flag | Meaning |\n|------|---------|\n| `--from <ref>` | The base ref: a commit, tag or branch. Required |\n| `--to <ref>` | The target ref (default: the working tree, scanned as `deps scan` does) |\n| `--ecosystem <ecosystem>` | `npm`, `nuget`, `maven` or `all` (default) |\n| `--include-dev` | Include dev and test dependencies |\n\nTransitive dependencies are always included. Output: `{ from, to, changes: [{ name,\necosystem, change, from, to, source }], summary: { added, removed, upgraded,\ndowngraded, unchanged } }`. `change` is `added`, `removed`, `upgraded` or\n`downgraded`. Unchanged packages are counted, not listed. `to` reads `working tree`\nwhen `--to` is left out.\n\nKnown quirks:\n\n- A ref git can\'t read (a typo, or one you haven\'t fetched) gives an empty\n inventory for that side, so a bad `--from` reports every package as `added`.\n Check the ref first.\n- Each package is keyed on ecosystem, name and source file, and one version per key\n survives. A package present at two versions can show a change that didn\'t happen.\n- Paths that git quotes (non-ASCII names) aren\'t read at a ref.\n- A ref that starts with `-`, or an empty `--from`, is refused with `INVALID_INPUT` before git runs. An empty `--to` means the working tree.\n\n### `toil util secrets scan`\n\nFinds credential-shaped strings before an agent or a person commits, pushes,\ncomments or posts them. It reads a file, a folder, stdin, text, or the\nrepository\'s staged or working-tree diff, and talks to nothing.\n\n```bash\ntoil util secrets scan --diff staged # before git commit\ntoil util secrets scan src/ # a folder, .gitignore respected\ntoil util secrets scan notes.md\ngh pr view 12 --json body -q .body | toil util secrets scan -\ntoil util secrets scan --text "$COMMENT"\n```\n\n| Argument / flag | Meaning |\n|-----------------|---------|\n| `[path]` | A file or folder inside the workspace. A folder is walked as `git ls-files --cached --others --exclude-standard` would list it. `-`, or nothing at all, reads stdin |\n| `--text <text>` | The content itself, instead of a file |\n| `--diff <kind>` | `staged` scans what the next commit holds (`git diff --staged`); `working` scans unstaged changes (`git diff`). Added lines only, in the workspace only. Runs the git on PATH |\n| `--allow-file <file>` | The allow file (default: `.toil/secrets-allow` at the workspace\'s top, when it exists) |\n\nPass one of a path, `--text` or `--diff`; two at once is `INVALID_INPUT`. Over\nMCP, pass `file`, `text` or `diff`.\n\nA folder that `.gitignore` excludes is walked as git lists it: only the files git\ntracks there. When that\'s none, the result has no findings and a\n`SECRETS_NOTHING_SCANNED` warning saying 0 files were scanned and why; name a file\nin the folder to scan that file.\n\n**The exit code is 1 when anything is found**, and 0 when nothing is, so a hook\nor a pipeline can gate on it. The envelope stays `ok: true` either way; `ok:\nfalse` (also exit 1) means the scan itself failed.\n\n**What it looks for:**\n\n- The rules the audit log redacts with, so toil has one definition of a\n secret: GitHub, GitLab, Slack (tokens and webhook URLs), AWS, SonarQube, `sk-`,\n Atlassian, Bitbucket Data Center, npm, Artifactory, Dynatrace, Figma and Azure\n DevOps tokens, Azure SAS signatures (`sig=`), JWTs, private keys, credentials\n in URLs, `Bearer` / `Basic` / `Token`\n values, `name=value` pairs whose name says secret (`password=`,\n `"apiToken":`, `--token=`), `curl -u user:pass`, and long random runs of\n letters and digits.\n- `high-entropy`: a run of 20 or more base64 or base64url characters, holding\n letters and digits, that those rules didn\'t catch and whose Shannon entropy\n is at least 4.2 bits per character.\n\nTwo things are set aside and counted instead of reported: Subresource Integrity\nchecksums (`sha512-\u2026` in lockfiles, counted in `summary.checksums`), and a named\nvalue that is a reference to a secret rather than one (`token: ${{ secrets.X }}`,\n`password=$DB_PASSWORD`, `<your-token>`, `xxx`, counted in\n`summary.placeholders`). Commits, digests and UUIDs aren\'t findings.\n\nOutput:\n\n```json\n{\n "source": { "kind": "staged", "path": null },\n "findings": [{ "file": "config/application.properties", "line": 4, "column": 28, "length": 14, "rule": "name-value", "confidence": "high", "entropy": 3.18, "preview": "\u2026", "fingerprint": "e594506f-49ad270a-55b41205-70d9b059" }],\n "allowed": [],\n "unreadable": [{ "file": "logo.png", "reason": "binary", "message": "logo.png is binary in the diff; its content wasn\'t scanned." }],\n "allowList": null,\n "summary": { "files": 1, "lines": 5, "findings": 1, "allowed": 0, "unreadable": 1, "checksums": 0, "placeholders": 0, "byRule": { "name-value": 1 } },\n "verified": { "passed": true, "checks": [] }\n}\n```\n\n- `file` is relative to the workspace, with forward slashes, or `null` for\n stdin and text. `line` and `column` start at 1; columns count UTF-16 code\n units. A private key spanning lines is one finding, with `endLine`.\n- `source.kind` is `file`, `folder`, `stdin`, `text`, `staged` or `working`.\n- `confidence` is `high` for a vendor\'s token format, `high` or `medium` for a\n value a name or scheme marks as secret (medium when it\'s short and plain),\n and graded by entropy for a random run (`low` below 3.5 bits per character).\n- **The full secret is never in the output**, nor in a warning, an error or the\n audit log, which keeps no copy of `text`. `preview` keeps at most 4\n characters at each end of a secret of 24 or more, 2 of one of 16 to 23, and\n none of a shorter one: `ghp_\u2026c9vB`, `\u2026`.\n- `fingerprint` identifies the value without revealing it: a salted scrypt,\n four groups of 8 hex digits. It\'s slow on purpose, so a short password can\'t\n be recovered from it by guessing at speed.\n\n**The allow file** lists known false positives, one fingerprint per line, copied\nfrom a finding. `#` starts a comment. It\'s matched by fingerprint only, never by\nthe raw value, so it\'s safe to check in. A finding it names goes in `allowed`\ninstead of `findings` and doesn\'t set the exit code. `allowList` says which file\nwas read, how many entries it had, how many lines weren\'t fingerprints, and how\nmany entries matched nothing. A line that isn\'t a fingerprint is ignored with a\n`SECRETS_ALLOW_INVALID` warning that gives its line number and never its text. A\nnamed `--allow-file` that doesn\'t exist is `INVALID_INPUT`.\n\n```text\n# .toil/secrets-allow\ne594506f-49ad270a-55b41205-70d9b059 # the test fixture\'s dummy password\n```\n\n**What it checks of its own result** (`verified`):\n\n- `finding.reread`: every finding is read again at its reported line, from the\n file on disk, from the index (`git show :<path>`) for a staged diff, or from\n what stdin or the text held. The same characters must be at the same column,\n with the same rule finding them. A mismatch warns `SECRETS_REREAD_MISMATCH`.\n- `preview.masked`: every preview is checked to hold none of the secret\'s\n middle. One that fails warns `SECRETS_PREVIEW_LEAK` and is replaced by `\u2026`.\n- `input.complete`: each file was read to its size on disk. For a diff this is\n `unchecked`, with an `UNVERIFIED` warning, since git\'s output has no size to\n compare with; the re-read checks each finding instead.\n\n**What it couldn\'t read is listed**, never skipped silently. `unreadable` holds\neach binary file, each file over 64 MiB, each one it couldn\'t open (a permission\nerror, say), each nested repository a folder scan didn\'t walk into, and each line\nover 4 MiB, of which only the start was scanned. Any of them adds a\n`SECRETS_UNREADABLE` warning. A single file named on the call that can\'t be read\nis an `INVALID_INPUT` error instead. `--diff working` also warns\n`SECRETS_UNTRACKED_NOT_SCANNED` with the number of untracked files, which no diff\nholds: scan the folder, or stage them, to include them.\n\n**A diff covers the workspace, not the whole repository.** When the workspace is\na folder inside the repository, changes outside it aren\'t scanned, and a\n`SECRETS_DIFF_PARTIAL` warning gives the number of changed files left out. To\ncheck a whole commit, run it with `--workspace` at the repository\'s top.\n\nKnown limits:\n\n- A diff and a file are scanned line by line, so a secret split across two lines\n (other than a private key) isn\'t found.\n- A private key spans lines only when its BEGIN line stands alone and an END\n line follows its body (base64, blank, `Proc-Type:` and `DEK-Info:` lines). It\'s\n then one finding, with `endLine`. When no END comes (another line, a gap\n between diff hunks, or the end of the file), the BEGIN line is reported on its\n own and the lines below it are scanned as usual.\n- A bare `key=` isn\'t treated as a secret\'s name, because in toil\'s inputs it\'s\n an issue, space or project key. A real key there is still caught by its shape\n or its entropy.\n\n### `toil util encode`\n\nEncodes or decodes base64, base64url, hex and URL percent-encoding, and hashes a\nfile with SHA-256, SHA-1 or MD5. Each result is checked before it\'s returned, and\n`data.verified` says how.\n\n```bash\ntoil util encode base64 --text \'you@example.com:abc12345\'\ntoil util encode base64 --decode mail-part.b64 --out logo.png\ntoil util encode url --text \'project = PAY AND assignee = "you@example.com"\'\ntoil util encode form --decode --text \'project+%3D+PAY+AND+assignee+%3D+%22you%40example.com%22\'\nprintf \'hello\' | toil util encode hex\ntoil util encode sha256 release.tgz\n```\n\n| Argument or flag | Meaning |\n|------------------|---------|\n| `<scheme>` | `base64`, `base64url`, `hex`, `url`, `form`, or a hash: `sha256`, `sha1`, `md5`. Required |\n| `[file]` | A file inside the workspace. `-`, or leaving out both the file and `--text`, reads stdin |\n| `--text <text>` | The content itself, instead of a file. It\'s encoded as UTF-8 |\n| `--decode` | Decode instead of encode. Not for a hash |\n| `--out <file>` | Write the result to this new file inside the workspace instead of returning it. Never replaces a file. Not for a hash |\n\nThe schemes:\n\n- **`base64`** is written padded. Decoding accepts it with or without padding, and\n ignores spaces and line breaks, so MIME-wrapped base64 reads as it is.\n- **`base64url`** (`-` and `_`) is written without padding, as JWTs use it, and\n read with or without.\n- **`hex`** is written in lower case and read in either. Spaces and line breaks are\n ignored; a `0x` prefix or `:` separators are not.\n- **`url`** is a URL component, written as JavaScript\'s `encodeURIComponent` writes\n it: letters, digits and `-_.!~*\'()` stay, every other byte becomes `%XX`.\n- **`form`** is one name or value of an `application/x-www-form-urlencoded` body:\n letters, digits and `*-._` stay, a space becomes `+`, and every other byte becomes\n `%XX`. Decode a body one field at a time. A whole body decodes, but its `=` and\n `&` come back the same as an encoded `%3D` and `%26`, so `roundtrip.encode`\n fails, as it should.\n\nOutput:\n\n- **Encode:** `{ operation: "encode", scheme, inputBytes, outputBytes, output, verified }`.\n- **Decode:** `{ operation: "decode", scheme, inputBytes, outputBytes, utf8, output, verified }`.\n `utf8` says whether the decoded bytes are valid UTF-8.\n- **Hash:** `{ operation: "hash", scheme, inputBytes, hex, base64, verified }`, the\n digest both ways.\n- With `--out`, `file` (the absolute path written) replaces `output`.\n\nThe input is bytes: a file or stdin is encoded or hashed exactly as it is, so\n`echo hello | toil util encode base64` includes the newline `echo` adds. Use\n`printf` or `--text` to leave it out. When decoding, one trailing line ending is\ndropped.\n\n**Decoded bytes that aren\'t valid UTF-8 are refused** with `INVALID_INPUT` unless\n`--out` names a file to write them to. JSON can only carry them as text, and any\ntext would be different bytes. Valid UTF-8 comes back as the text it is.\n\nWhat `data.verified` checks:\n\n| Check | What it means |\n|-------|---------------|\n| `roundtrip.decode` | An encode was decoded back, and gave exactly the input |\n| `roundtrip.encode` | A decode was encoded again, and gave the input, allowing for whitespace, padding, the case of hex and `%XX`, and `%20` for `+` in a form |\n| `input.complete` | The bytes read equal the file\'s size on disk, so a read that stopped short can\'t pass. Unchecked for stdin, which has no size |\n| `output.file` | The file written was read back, and holds exactly the bytes written |\n\nA failed check sets `verified.passed` to `false` and adds a warning:\n`ENCODE_ROUNDTRIP_MISMATCH`, `INPUT_INCOMPLETE` or `ENCODE_OUTPUT_MISMATCH`. Input\nthat decodes but fails `roundtrip.encode` isn\'t how the scheme writes those bytes.\nFor example, base64 `QR==` decodes to `A`, but base64 writes `A` as `QQ==`, and a URL\nwith a space left in it isn\'t encoded. Check that it wasn\'t changed on the way.\n\nErrors:\n\n- Text that isn\'t the scheme is `INVALID_INPUT`, naming the offset of the first\n character that\'s wrong but never the character, in case the text is a credential.\n A base64 character that only base64url uses (or the other way round) says to try\n the other scheme.\n- A file to decode that looks binary (a NUL byte), `--decode` or `--out` with a hash,\n and a scheme toil doesn\'t have are `INVALID_INPUT`.\n- Encoding or decoding reads at most 64 MiB. A hash of a file streams, with no\n limit; stdin is held in memory, so it keeps the 64 MiB limit.\n\nMD5 and SHA-1 are here to match checksums that other tools publish, not to protect\nanything. The audit log keeps only a hash of `--text`.\n\n### `toil util cert`\n\nDecodes X.509 certificates, one or a chain bundle, in PEM or DER, so you can\nexplain a TLS failure from the files. It never connects to the host the certificate\nis for: pass the file the server is configured with, or the chain a client saved.\n\n```bash\ntoil util cert chain.pem\ntoil util cert chain.pem --host api.imagile.dev\ntoil util cert server.der\ncat chain.pem | toil util cert -\n```\n\n| Argument or flag | Meaning |\n|------------------|---------|\n| `[file]` | A file in the workspace, PEM or DER. `-`, or leaving it out, reads stdin |\n| `--text <text>` | The PEM itself, instead of a file. Over MCP, `text` is read as UTF-8, so a DER certificate goes as `file` |\n| `--host <host>` | A host name or IP address: do the first certificate\'s SANs cover it? |\n\nOutput: `{ format, certificates, skipped, chain, host, verified }`. Each\ncertificate is `{ position, line, offset, subject, issuer, sans, serial, validity:\n{ notBefore, notAfter, daysLeft, status }, key: { type, bits, curve },\nsignatureAlgorithm: { name, oid }, selfSigned, basicConstraints: { ca, pathLength },\nkeyUsage, extendedKeyUsage, fingerprints: { sha1, sha256 } }`. `position` counts\nevery block in a PEM bundle (or element in a DER one) from 1, `line` is where a PEM\nblock starts and `offset` where a DER certificate does. `status` is `valid`,\n`expired` or `not-yet-valid`, and `daysLeft` is negative once expired.\n`basicConstraints`, `keyUsage` and `extendedKeyUsage` are null when the certificate\ndoesn\'t have that extension.\n\nWhat it checks, in `data.verified` (a failure also warns under its code):\n\n| Check | Means | Fails with |\n|-------|-------|------------|\n| `bundle.readable` | Every block meant to be a certificate decodes | `CERT_UNREADABLE` |\n| `decode.matchesNode` | toil\'s DER reader and `node:crypto` agree on the serial and CA flag, and nothing follows the certificate in its block | `CERT_DECODE_MISMATCH` |\n| `validity.notExpired`, `validity.started` | Each certificate is inside its validity window now | `CERT_EXPIRED`, `CERT_NOT_YET_VALID` |\n| `chain.order` | Each certificate\'s issuer is the next one\'s subject | `CERT_CHAIN_ORDER` |\n| `chain.signature` | Where the names match, each signature verifies with the next certificate\'s key, and a self-issued last certificate with its own | `CERT_SIGNATURE_MISMATCH` |\n| `chain.root` | Unchecked (`UNVERIFIED`) when the last certificate isn\'t self-signed, so its issuer doesn\'t follow it: the chain is checked only as far as the bundle goes | |\n| `host.covered` | With `--host`, a DNS or IP SAN of the first certificate covers it | `CERT_HOST_MISMATCH` |\n| `input.complete` | The whole file was read (unchecked for stdin) | `INPUT_INCOMPLETE` |\n\n- The chain is checked in the order given, leaf first. When it\'s out of order but\n is one chain in another order, `chain.suggestedOrder` lists the positions in the\n right order and `CERT_CHAIN_REORDER` says so.\n- `chain.inOrder` is true when every link\'s names match and every signature\n checked verifies. `chain.root` is `included` when the last certificate is\n self-signed. Nothing is checked against a trust store: a chain that verifies to\n a root in the bundle isn\'t thereby trusted.\n- `--host` follows what browsers do: SANs only, never the subject CN, and a\n wildcard covers exactly one label (`*.imagile.dev` covers `api.imagile.dev`, not\n `imagile.dev` or `a.api.imagile.dev`). `host.explanation` says why it\'s covered\n or not.\n- A PEM block that isn\'t a certificate is skipped, listed in `skipped` and named in\n a `CERT_BLOCK_SKIPPED` warning. A private key is never read, and\n `CERT_PRIVATE_KEY_IN_INPUT` says one was there. `CERTIFICATE` and\n `X509 CERTIFICATE` blocks are read; `TRUSTED CERTIFICATE`, PKCS#7 (`.p7b`) and\n PKCS#12 (`.pfx`) are not.\n- In DER input a damaged certificate ends the reading, since nothing says where the\n next one starts; it\'s reported at its byte offset.\n- Input with no certificate that can be read fails with `INVALID_INPUT`, naming\n each block and why.\n\n### `toil util semver`\n\nVersions and ranges in the grammar of the ecosystem they come from. Pick it with\n`--ecosystem`: `npm` (the default), `nuget` or `maven`.\n\n- **npm:** SemVer 2.0.0 versions (`1.2.3`, `1.2.3-rc.1+build.5`; a leading `v` is\n allowed) and npm\'s ranges, as `package.json` takes them: `^1.2.3`, `~1.2`, `1.x`, `>=1.0.0 <2.0.0`,\n `1.0.0 - 2.0.0`, joined with `||`. A prerelease satisfies a range only when the\n range names a prerelease of the same `major.minor.patch`, unless you pass\n `--include-prerelease`. There\'s no loose mode that turns text that isn\'t a\n version into one.\n- **nuget:** one to four numbers (`1`, `1.0` and `1.0.0.0` are one version), then\n an optional `-prerelease` and `+metadata`. Labels compare case-insensitively.\n Ranges are interval notation: `1.0` (at least 1.0), `[1.0]`, `[1.0,2.0)`,\n `(,2.0]`. A prerelease inside the bounds satisfies the range. Floating versions\n (`1.*`, `1.0.0-*`) are refused, because what one picks depends on the feed.\n- **maven:** Maven\'s own ordering: `alpha < beta < milestone < rc < snapshot <\n release < sp`, `1`, `1.0` and `1.0.0.Final` are one version, and `1a1` is\n `1-alpha-1`. A version is letters, digits, `.`, `-`, `_` and `+` with at least\n one digit, so an unresolved `${property}` is reported, not ordered. Ranges are\n `[1.0,2.0)`, `[1.0]` and `(,1.0],[1.2,)`. A bare version is a soft requirement\n that any version satisfies, and says so in a `MAVEN_SOFT_REQUIREMENT` warning.\n\nA version or range that doesn\'t parse in the chosen grammar is `INVALID_INPUT`,\nwith the reason and an example of what fits. Build metadata never affects order.\n\n```bash\ntoil util semver compare 1.0.0-rc.10 1.0.0-rc.9\ntoil util semver satisfies 1.3.0-rc.1 \'^1.2.0\' --include-prerelease\ntoil util semver satisfies 5.3.39 \'[5.0,6.0)\' --ecosystem maven\ntoil util semver sort versions.txt --range \'^5.0.0\'\ntoil util semver bump 1.2.3 prerelease --preid rc\n```\n\n| Command | Arguments and flags | Output |\n|---------|---------------------|--------|\n| `compare <a> <b>` | `--ecosystem <ecosystem>` | `{ ecosystem, a, b, order, higher, difference, normalized: { a, b }, verified }`. `order` is -1, 0 or 1 for a against b, `higher` is `a`, `b` or null, and `difference` is the most significant part they differ in: `major`, `minor`, `patch`, `revision` (NuGet\'s fourth part, or Maven\'s), `prerelease`, `qualifier` (Maven) or null |\n| `satisfies <version> <range>` | `--ecosystem <ecosystem>`, `--include-prerelease` | `{ ecosystem, version, range, normalizedRange, satisfies, verified }` |\n| `sort [file]` | `--text <text>`, `--ecosystem <ecosystem>`, `--range <range>`, `--include-prerelease` | `{ ecosystem, count, sorted, invalid, verified }`, lowest first, plus `{ range, normalizedRange, satisfying, highest }` with `--range` |\n| `bump <version> <release>` | `--ecosystem <ecosystem>`, `--preid <id>` | `{ ecosystem, version, release, preid, result, verified }` |\n\n- **`sort`** reads a file in the workspace, stdin (`-`, or no file), or `--text`.\n Versions go one per line or separated by spaces. An entry that doesn\'t parse is\n left out of the sort and listed in `invalid` with its line and the reason, with a\n `SEMVER_INVALID_VERSION` warning.\n- **`bump`** takes `major`, `minor` or `patch` in every ecosystem. npm also takes\n `premajor`, `preminor`, `prepatch`, `prerelease` and `release`, the bumps npm\n publishes with, and `--preid` names the prerelease (`1.2.3` `prerelease --preid rc` is\n `1.2.4-rc.0`). A NuGet result has three parts, with the revision and labels\n dropped. Maven bumps the leading numbers and drops the qualifier\n (`1.2.3-SNAPSHOT` `minor` is `1.3.0`).\n\n**What it checks** (`verified`, with failures as warnings):\n\n- `sort.transitive`: every pair in the sorted list is in order, so a comparison\n where a < b and b < c but not a < c can\'t hide. Up to 2,000 versions; past that,\n each against its neighbour, reported as `APPROXIMATED`.\n- `sort.antisymmetric`, `sort.complete`: each neighbouring pair compares the same\n both ways round, and every entry is either sorted or listed as invalid.\n- `range.boundaries`, `range.answers`: each answer agrees with the range\'s\n intervals, worked out by comparison alone, at the range\'s boundary versions and\n at every version asked about. A range with no bounds (`*`) has none to test, and\n says so with `UNVERIFIED`.\n- `compare.antisymmetric`, `diff.consistent`, `bump.increases`,\n `version.normalized`: b against a is the reverse of a against b, a difference is\n named exactly when the versions differ, a bump goes up, and a normalised version\n reads back as the same version.\n- `input.complete`: the whole file was read. stdin has no size to compare with, so\n it\'s `UNVERIFIED`.\n\n`diff` names the most significant part that changed, the same rule in every\necosystem; it never answers `premajor` or the like.\n\n### `toil util report`\n\nOne JSON summary of a report that CI or a scanner wrote: JUnit XML, TRX, SARIF\n2.1.0, lcov or Cobertura. It reads the file and nothing else, and checks the report\nagainst its own declared totals.\n\n```bash\ntoil util report target/surefire-reports/TEST-dev.imagile.OrderTest.xml\ntoil util report TestResults/build.trx\ntoil util report coverage/lcov.info --lowest 5\ntoil util report results.sarif\ncat coverage.xml | toil util report --format cobertura\n```\n\n| Argument / flag | Meaning |\n|-----------------|---------|\n| `[file]` | The report, inside the workspace. `-`, or no file and no `--text`, reads stdin |\n| `--text <text>` | The report itself, instead of a file |\n| `--format <format>` | `junit`, `trx`, `sarif`, `lcov` or `cobertura`. Left out, it\'s detected from the content: the root element for XML (`<testsuites>` or `<testsuite>`, `<TestRun>`, `<coverage>`), `"runs"` for SARIF, a first `TN:` or `SF:` line for lcov |\n| `--lowest <n>` | How many of the lowest-covered files to list (default 10, up to 1000) |\n\nOver MCP the tool is `util_report`, with `file` or `text`, `format` and `lowest`.\n\nOutput: `{ format, formatFrom, tests, findings, coverage, skipped, verified }`.\n`formatFrom` is `content` or `flag`. One of `tests`, `findings` and `coverage` is\nfilled in, by format, and the other two are `null`.\n\n- **`tests`** (JUnit, TRX): `{ suites, totals: { tests, passed, failures, errors,\n skipped, flaky, other }, failures: [{ suite, name, className, kind, type,\n message, file, line, location, stack, stackLines }] }`. The totals are recounted\n from the cases, never copied from the report. `kind` is `failure` or `error`.\n `stack` is the first 15 lines, and `stackLines` how many there were. `location` is\n `report` when the report states `file` or `line`, and `stack` when they were read\n from the first stack frame naming the test\'s class or method (an `APPROXIMATED`\n warning says how many). It\'s `null` when neither has one.\n- **`findings`** (SARIF): `{ runs: [{ tool, version, results }], total, byLevel,\n results: [{ tool, rule, level, kind, file, line, message, suppressed }] }`. `level`\n follows the spec: the result\'s own, else its rule\'s default, else `warning` for a\n failing result and `none` for any other. `file` is the first location\'s URI as\n written, and `line` its `startLine`.\n- **`coverage`** (lcov, Cobertura): `{ sources, totals: { lines, branches }, files:\n [{ file, lines, branches }], lowest }`. Each figure is `{ covered, total, percent }`,\n with `percent` rounded to two places (`null` when there\'s nothing to cover).\n `branches` is `null` where the report has no branch data. `lowest` lists the\n `--lowest` files with the lowest line coverage, leaving out files with no lines.\n- **`skipped`**: `{ count, elements: [{ element, count, reason }] }`, every element\n (or lcov record) the reader met and didn\'t read, also warned as\n `REPORT_ELEMENTS_SKIPPED`. Known parts that hold nothing it summarises\n (`system-out`, `properties`, TRX\'s settings and lists, Cobertura\'s per-method copies\n of the lines) aren\'t counted.\n\nWhat `verified` checks:\n\n| Format | Check | Warning when it fails |\n|--------|-------|-----------------------|\n| JUnit | Each suite\'s (and `<testsuites>`\') declared `tests`, `failures`, `errors` and `skipped`, recounted from its cases, nested suites included | `REPORT_TOTALS_MISMATCH`, naming both numbers |\n| TRX | `<Counters>`\' `total` and each outcome counter, recounted from the results\' `outcome` | `REPORT_TOTALS_MISMATCH` |\n| Cobertura | Every stated `line-rate` and `branch-rate` (class, package and root), to within one unit of its last written decimal, and the root\'s `lines-covered`, `lines-valid`, `branches-covered` and `branches-valid` | `REPORT_COVERAGE_MISMATCH` |\n| lcov | Each record\'s `LF`, `LH`, `BRF`, `BRH`, `FNF` and `FNH`, recounted from its `DA`, `BRDA`, `FN` and `FNDA` lines | `REPORT_COVERAGE_MISMATCH` |\n| SARIF | Each `ruleIndex` points at the rule its `ruleId` names | `REPORT_SARIF_INCONSISTENT` |\n| All | The whole input was read (`input.complete`) | `INPUT_INCOMPLETE`, or `INPUT_TRUNCATED` at the cap |\n\nWhat it can\'t check is reported as `UNVERIFIED`, never as passed: a JUnit report\nthat declares no totals, SARIF (which declares none), a TRX counter left at `0` over\nresults with that outcome (VSTest leaves `notExecuted` at 0, for one), and the size\nof stdin. TRX\'s `executed` isn\'t compared, because writers disagree on what it\ncounts.\n\nFormats it reads:\n\n- **JUnit:** Maven Surefire\'s, the Jenkins shape (nested `<testsuite>`s, `status`,\n `assertions`, `disabled`) and the Azure DevOps shape (the VSTest JUnit logger\'s).\n Surefire\'s `flakyFailure` and `flakyError` mean a rerun passed: the case counts as\n passed and in `flaky`. A case with `<error>` is an error, else one with\n `<failure>` is a failure, else one with `<skipped>` is skipped.\n- **TRX:** `dotnet test --logger trx` and Visual Studio\'s. Top-level results are\n counted, as the counters count them, and a data-driven test\'s inner rows aren\'t.\n `failures` is `Failed`; `errors` is `Error`, `Timeout` and `Aborted`; `skipped` is\n `NotExecuted` and `NotRunnable`; any other outcome is `other`. `suites` is the\n number of test classes, and a failure\'s `suite` is its class.\n- **SARIF 2.1.0:** any tool\'s. A rule reference with a `toolComponent` index is\n looked up in that entry of `tool.extensions` (CodeQL query packs); one that names\n its component only by `guid` can\'t be found, so `sarif.ruleIndex` is `UNVERIFIED`\n and the level falls back to `warning`. A file with another `version` is read as\n 2.1.0, with an `APPROXIMATED` warning. A run whose invocation says it failed warns\n `REPORT_TOOL_FAILED`.\n- **lcov:** `SF` to `end_of_record` records, including lcov 2\'s `FNL` and `FNA`.\n `FNH` is recounted as distinct functions hit: `FNA` by index, so a function\'s\n aliases count once, and `FNDA` by name. A file in several records is merged, and a\n line is covered when any record hit it.\n- **Cobertura:** coverlet\'s, coverage.py\'s and others\'. Classes in the same file are\n added together, and branch counts come from `condition-coverage="50% (1/2)"`.\n\nLimits: XML and lcov stream, so memory stays flat for a report of any size, apart\nfrom the failures it lists, up to the 64 MiB input cap. At the cap the read stops,\n`INPUT_TRUNCATED` says so, `input.complete` fails, and what came before the cut is\nsummarised; a suite the cut left open isn\'t compared. SARIF is JSON and is read\nwhole, so a SARIF file over the cap is `INVALID_INPUT`. Malformed XML or JSON is\n`INVALID_INPUT` with the line and column. So is a document whose format can\'t be\ndetected, or whose root doesn\'t match `--format`, with a fix naming `--format`.\n\n### `toil util log`\n\nTriages a large log (a CI console, a Maven, npm or dotnet build, a test run) into\nwhat\'s worth reading: its error and warning lines grouped by signature, each with the\nstack trace that follows it. It reads the file only, streams it, and holds memory\nconstant however large the log is.\n\n```bash\ntoil util log build.log\ntoil util log console.log --level error --context 3\ntoil util log console.log --since 2026-10-14T09:12:00Z --grep \'Failed to execute\'\nsome-build 2>&1 | toil util log -\n```\n\n| Argument or flag | Meaning |\n|------------------|---------|\n| `[file]` | The log, inside the workspace. `-`, or no file and no `--text`, reads stdin |\n| `--text <text>` | The log itself, instead of a file |\n| `--since <timestamp>` | Only lines dated at or after this ISO 8601 time (`2026-10-14`, `2026-10-14T09:12:00Z`, `"2026-10-14 09:12:00"`). A line with no date takes the date of the last dated line before it. Without a zone, a time is read as UTC |\n| `--level <level>` | `warning` (default) reports errors and warnings; `error` reports errors only |\n| `--grep <regex>` | Only error and warning lines matching this JavaScript regular expression (case-sensitive, no slashes or flags). An error also matches when the exception line heading its trace does (`--grep IllegalStateException`). Frames aren\'t searched; `LOG_GREP_STACK_ONLY` says when only they matched |\n| `--max-groups <n>` | The most groups to return, default 50, up to 1000 |\n| `--context <n>` | Lines to show before and after each group\'s sample, default 0, up to 20 |\n\nOver MCP the tool is `util_log`, with `file` (a path in the workspace) or `text`, and\nthe same fields: `since`, `level`, `grep`, `maxGroups`, `context`.\n\nHow it reads a log:\n\n- **Timestamps:** a leading timestamp, bracketed (Jenkins\' timestamper) or bare (CI\n runners, log4j, Serilog), is set aside before anything else, so it never splits a\n group.\n- **Levels:** the first level word decides (`ERROR`, `FATAL`, `SEVERE`, `WARN`,\n `WARNING`, `INFO`, `DEBUG` \u2026, and npm\'s `npm error` / `npm warn`). A line tagged\n `INFO`, or with no tag, is still an error by its shape: `BUILD FAILURE`, `FAILED`,\n `error CS0246:`, `error TS2322:`, `TypeError: \u2026`, `Unhandled exception.`, an eslint\n or vstest failure line. A tag with nothing after it (`[ERROR] `) is not a group.\n- **Signatures:** dates and times, UUIDs, hex and every number are replaced, and\n spaces collapsed. Codes such as `CS0246` and `TS2322` keep their digits, and paths\n and quoted names stay, so two different errors stay apart.\n- **Stack traces:** Java (`at \u2026(File.java:12)`, `Caused by:`, `... 14 more`), .NET\n (`at \u2026 in file:line 9`, `--->`, `--- End of inner exception stack trace ---`), Node\n (`at fn (file:12:3)`) and Python (`Traceback (most recent call last):`, printed\n before its exception) are joined to the error they belong to, with the exception\n line that heads one. An exception line joins an error, never a warning: after a\n warning it\'s an error of its own. A trace is reported for each group\'s first occurrence, up to\n 50 lines.\n\nOutput:\n\n```json\n{\n "lines": { "total": 76, "error": 20, "warning": 5, "other": 35, "stack": 12, "unclassified": 4 },\n "matched": 25, "filtered": 0, "groupsTotal": 18, "truncated": false, "ungrouped": 0, "unjoinedFrames": 0,\n "groups": [{\n "level": "error",\n "signature": "[ERROR] /build/ledger/Reconciler.java:[<n>] cannot find symbol",\n "count": 4, "firstLine": 27, "lastLine": 52,\n "sample": "[ERROR] /build/ledger/Reconciler.java:[54,38] cannot find symbol",\n "trace": { "kind": "java", "firstLine": 57, "lastLine": 68, "frames": 12, "lines": ["\u2026"] },\n "context": { "before": [{ "line": 26, "text": "\u2026" }], "after": [{ "line": 28, "text": "\u2026" }] }\n }],\n "verified": { "passed": true, "checks": [{ "check": "lines.reread", "status": "passed", "checked": 36, "failed": 0 }] }\n}\n```\n\nGroups are errors first, then warnings, each in order of first appearance. `lines`\nclasses every line once: `other` is a level below warning, `stack` a trace line, and\n`unclassified` a line with no level at all. `filtered` counts the error and warning\nlines `--since`, `--level` or `--grep` left out.\n\nIt checks its own answer, in `data.verified`:\n\n- **`lines.reread`:** every group\'s first line is read again from the file and must\n be its sample, and its last line must still have its signature. `trace.reread`\n does the same for every trace line shown. A mismatch is `LOG_LINE_MISMATCH`, which\n usually means the file changed while it was read.\n- **`groups.sum`, `lines.sum`, `filter.sum`:** the group counts add up to the matched\n lines, the line classes to the lines read, and matched plus filtered to the error\n and warning lines. A mismatch is `LOG_COUNT_MISMATCH`.\n- **`input.complete`:** the bytes read equal the file\'s size. It\'s `unchecked` for\n stdin and text.\n\nWhat it reports in `meta.warnings` rather than leave out: `LOG_UNCLASSIFIED` (lines\nwith no level, in no group), `LOG_GROUPS_TRUNCATED` (more groups than\n`--max-groups`), `LOG_UNGROUPED` (matched lines whose signature came after the first\n2,000 distinct ones, counted but not grouped, which is what keeps memory constant),\n`LOG_TRACE_UNJOINED` (trace lines with no error before them), `LOG_GREP_STACK_ONLY`\n(`--grep` matched only stack trace lines), `LOG_SINCE_UNDATED`\n(lines `--since` couldn\'t date, kept), and `APPROXIMATED` for a line longer than\n4,096 characters (grouped by its start) or a `--since` compared with times that had\nno zone.\n\nA file streams with no size limit. stdin and `--text` are held in memory, up to\n64 MiB, so pass a file for anything bigger.\n\n`--grep` runs in a worker thread, a batch of up to 4,096 lines at a time, each batch\nwith 2 seconds and 256 MB. A pattern that backtracks without end on some line, such as\n`(a+)+b`, fails the command with `TIMEOUT` naming the lines, rather than holding it.\n\n### `toil util size`\n\nHow big a file or folder is before you read it, so an agent can budget its\ncontext: bytes, lines and an estimated token count, and for one file an outline\nwith line ranges, so you can read just the part you need.\n\n```bash\ntoil util size src/areas/util/size.ts\ntoil util size src --depth 2 --top 5\ngit show HEAD:README.md | toil util size - --language markdown\n```\n\n| Argument / flag | Meaning |\n|-----------------|---------|\n| `[file]` | A file or folder inside the workspace. `-` (or nothing) reads stdin |\n| `--text <text>` | The content itself, instead of a file |\n| `--language <language>` | Outline it as this language: `typescript`, `javascript`, `python`, `csharp`, `java`, `go`, `markdown`, `json` or `yaml`. Needed for stdin and `--text`; for a file it overrides the extension |\n| `--top <n>` | For a folder: how many of the largest files to list (default 10) |\n| `--depth <n>` | For a folder: how many levels of subfolders the tree shows (default 3). Deeper folders still count in their parent\'s totals, and `foldersHidden` says how many were left out |\n\n**Tokens are an estimate**: `ceil(characters / 4)` per file, counting Unicode code\npoints. No model\'s tokenizer is bundled, and real counts vary by model and\ncontent. Every result says so in `tokenMethod` and with an `APPROXIMATED` warning.\n\n**For a file**: `{ kind: "file", path, language, bytes, lines, tokens, tokenMethod,\noutline, notOutlined, verified }`. `outline` is `{ precision, method, symbols }`,\neach symbol `{ name, kind, startLine, endLine, container }` (headings add `level`):\n\n- **Code** (`precision: "syntactic"`): TypeScript and JavaScript (`.ts`, `.tsx`,\n `.mts`, `.cts`, `.js`, `.jsx`, `.mjs`, `.cjs`), Python, C#, Java and Go. Functions,\n classes, interfaces, types, enums, namespaces, methods, constructors, C#\n properties and exported names. It\'s a pure-JavaScript scan that skips comments\n and strings and matches braces (indentation for Python), not a compiler, so\n `method` says what each language covers. Function bodies aren\'t searched, and\n fields aren\'t listed. `container` is the enclosing class or namespace.\n- **Markdown**: ATX and setext headings, outside code fences and front matter.\n- **JSON and YAML** (`precision: "parsed"`): the top-level keys, found by scanning\n and held against what the parser returns.\n\nWhen there\'s no outline, `outline` is null and `notOutlined` says why: `binary` (a\nNUL byte in the first 8,000 bytes; lines and tokens are null too),\n`unsupported-language`, `parse-error` (with the line, never the text, or that it\nnests too deep to outline; also a `SIZE_PARSE_ERROR` warning) or `too-large` (over\n8 MiB; it\'s still counted).\n\nThe outline is made in a worker thread with 10 seconds and 512 MB; a file at the\n8 MiB limit takes under 2 seconds. Past either, the command fails with `TIMEOUT` or\n`INVALID_INPUT` naming the file and the limit.\n\n**For a folder**: `{ kind: "folder", path, tokenMethod, totals, tree, largest,\nskipped, verified }`. It lists files the way `deps scan` does, skipping what\n`.gitignore` ignores. `totals` and every `tree` node hold `files`, `bytes`, `lines`,\n`tokens` and `binaryFiles`; binary files count in files and bytes only. Folders are\nsorted largest first. `largest` names the biggest files with their language.\n`skipped` lists what wasn\'t counted, with the reason: `unreadable` (with a\n`SIZE_FILES_SKIPPED` warning), `not-a-file` or `nested-repository`.\n\n**What it checks**, in `data.verified`:\n\n- `outline.start`: each symbol\'s start line, re-read from the input, names it.\n- `outline.range` and `outline.nesting`: each range is inside the file and in\n order, and a member sits inside its container.\n- `outline.keys`: JSON and YAML keys match the parser\'s.\n- `counts.reread`: the outline\'s full read gives the same bytes and lines.\n- `totals.sum` and `tree.sum`: the totals equal the files added up, and each\n folder equals its own files plus its subfolders.\n- `input.complete`: every file was read to its size on disk.\n\nA failed check sets `verified.passed` to false and warns `SIZE_OUTLINE_MISMATCH`,\n`SIZE_TOTALS_MISMATCH` or `SIZE_COUNTS_MISMATCH`.\n\n### Time: `toil util time`\n\nDate and time arithmetic on the time zone data Node ships (IANA, through `Intl`);\ntoil bundles no zone database of its own, and nothing reads the network. Each\ncommand checks its own answer a second way and reports the checks in\n`data.verified` (`{ passed, checks }`), with anything it couldn\'t check or had to\napproximate in `meta.warnings` as `UNVERIFIED` or `APPROXIMATED`.\n\nTimes are ISO 8601: a date (`2026-03-08`), a wall clock (`2026-03-08T02:30`), or an\ninstant with `Z` or an offset (`2026-03-08T07:30:00Z`, `2026-03-08T02:30:00-05:00`).\n`@1760000000` is epoch seconds, and `now` is the current time, read once per call.\nFields out of range (`2026-02-29`, `24:00`, a leap second) are `INVALID_INPUT`,\nnever rolled over. Digits below a millisecond are dropped with an `APPROXIMATED`\nwarning. Zones are IANA names (`America/New_York`); an unknown one is\n`INVALID_INPUT`.\n\n**DST.** A wall clock a zone skipped (spring forward) or showed twice (fall back) is\nalways reported, in `data` as a `dst` object and in `meta.warnings` as\n`TIME_DST_GAP` or `TIME_DST_OVERLAP`. A gap is read as the time the clocks showed\nafter the jump (02:30 becomes 03:30) and an overlap as the earlier of the two. Give\nthe time an offset to choose otherwise.\n\n#### `toil util time convert`\n\n```bash\ntoil util time convert 2026-03-08T02:30 --zone America/New_York --to UTC --to Europe/London\ntoil util time convert now --to Asia/Kolkata\n```\n\n| Argument or flag | Meaning |\n|------------------|---------|\n| `<time>` | The time to convert |\n| `--zone <zone>` | The zone of a time written without an offset. Required for one; refused for a time that has an offset |\n| `--to <zone>` | A zone to convert to (repeatable; default `UTC`) |\n\nOutput: `{ input, instant, epochMs, source: { kind, zone, offset, dst? }, results:\n[{ zone, local, offset, offsetSeconds, dst? }], verified }`. `local` is the time in\nthat zone with its offset. Checks: each result reads back as the same instant\n(`convert.roundtrip`), the zone shows that wall clock then (`convert.zone`), and a\nwall-clock input is what its zone shows at the instant found (`convert.source`). A\nfailure warns `TIME_ROUNDTRIP_MISMATCH`.\n\n#### `toil util time duration`\n\n```bash\ntoil util time duration P1DT2H30M\ntoil util time duration --seconds 93784.5\n```\n\n| Argument or flag | Meaning |\n|------------------|---------|\n| `<duration>` | An ISO 8601 duration to read: `PT1H30M`, `P1Y2M10DT2H`, `PT0.5S`, `-PT15M`. Only the last part may have a fraction |\n| `--seconds <seconds>` | Instead, a number of seconds to write as a duration |\n\nOutput: `{ input, iso, negative, parts: { years, months, weeks, days, hours,\nminutes, seconds }, totalSeconds, text, verified }`. `iso` is the canonical text.\nSeconds are written in hours, minutes and seconds only (`PT26H3M4.5S`), since a day\nisn\'t always 24 hours. Years and months have no fixed length, so `totalSeconds` is\n`null` with an `UNVERIFIED` warning; days and weeks count as 24 hours and 7 days,\nwith an `APPROXIMATED` warning. Check: the canonical text reads back as the same\nparts (`duration.roundtrip`, warning `DURATION_ROUNDTRIP_MISMATCH`).\n\n#### `toil util time business-days add` and `diff`\n\n```bash\ntoil util time business-days add 2026-12-23 3 --holidays holidays-2026.txt\ntoil util time business-days add 2026-12-28 -1\ntoil util time business-days diff 2026-12-24T15:00 2026-12-29T10:00 --zone America/Chicago --holiday 2026-12-25\n```\n\n| Argument or flag | Meaning |\n|------------------|---------|\n| `<start>` | The start time or date |\n| `<days>` | `add`: business days to add; negative subtracts |\n| `<end>` | `diff`: the end time or date |\n| `--zone <zone>` | The zone whose calendar days count, and the zone of a time without an offset (default `UTC`) |\n| `--holidays <file>` | A file in the workspace: one `YYYY-MM-DD` per line, optionally followed by a name; `#` lines are comments. Any other line is `INVALID_INPUT` naming it |\n| `--holiday <date>` | A holiday as `YYYY-MM-DD` (repeatable) |\n\nBusiness days are Monday to Friday, less the holidays given. No country\'s holidays\nare built in: list the dates the office is actually shut (the observed Friday, not\nthe Saturday it stands in for).\n\n`add` counts as a spreadsheet\'s `WORKDAY` does: the start never counts, each step\nlands on the next business day, and `0` returns the start unchanged. A time of day\nis kept, and a result in a DST gap or overlap is warned about. Output: `{ start,\ndays, zone, result, weekday, skipped: { weekendDays, holidays }, holidaysListed,\ndst?, verified }`. Checks: the business days between start and result, counted\nagain day by day, number `days` (`business.count`); the result is a business day\n(`business.landing`); and it\'s on the right side of the start\n(`business.direction`). A failure warns `BUSINESS_DAYS_MISMATCH`.\n\n`diff` measures the time between two times that falls on business days in the\nzone. A date means midnight. Output: `{ start, end, zone, negative, businessDays,\nhours, duration, totalBusinessSeconds, elapsedSeconds, holidays, verified }`:\n`businessDays` is whole 24-hour days of business time, `hours` what\'s left over,\nand `duration` the same, exactly (`PT43H`). DST days count as the 23 or 25 hours\nthey are. Checks: business time plus the rest adds up to the elapsed time\n(`business.partition`), and the days and hours make the business time\n(`business.total`), warning `BUSINESS_TIME_MISMATCH`.\n\n#### `toil util time cron`\n\n```bash\ntoil util time cron "*/15 9-17 * * 1-5" --zone Europe/London --count 10\ntoil util time cron "0 0 12 ? * MON#2" --dialect quartz\ntoil util time cron "H H(0-7) * * 1-5" --dialect jenkins --job platform/api-build\n```\n\n| Argument or flag | Meaning |\n|------------------|---------|\n| `<expression>` | The cron expression, quoted |\n| `--dialect <dialect>` | `standard`, `quartz` or `jenkins` (default: detected: 6 or 7 fields is `quartz`, an `H` is `jenkins`, otherwise `standard`) |\n| `--zone <zone>` | The zone the schedule runs in (default `UTC`) |\n| `--from <time>` | List runs after this time (default `now`) |\n| `--count <n>` | How many run times to list, 1 to 100 (default 5) |\n| `--job <name>` | The Jenkins job\'s full name (`folder/job`), which `H` is hashed from. Required when the expression uses `H` |\n\nThe dialects:\n\n- **standard**: five fields, minute hour day-of-month month day-of-week, as the classic\n crontab reads them. Names (`JAN`, `MON`), ranges, lists and steps (`*/15`,\n `1-30/5`, `5/15`); day-of-week 0 to 7, with 0 and 7 both Sunday. Macros `@yearly`,\n `@annually`, `@monthly`, `@weekly`, `@daily`, `@midnight` and `@hourly`; `@reboot`\n is refused, since it has no times. When neither day field starts with `*`, a day\n matching **either** runs. A detected standard expression with both day fields set\n warns `CRON_DIALECT_ASSUMED`, since Jenkins reads it differently.\n- **quartz**: six or seven fields, second first and an optional year (1970 to 2099)\n last. Day-of-week is 1 to 7 from Sunday. One of the day fields must be `?`.\n Day-of-month takes `L`, `L-3`, `15W` (the weekday nearest the 15th, inside the\n month) and `LW`; day-of-week takes `6L` (the last Friday) and `6#3` (the third\n Friday). A backwards range wraps (`FRI-MON`, `22-2`).\n- **jenkins**: five fields like standard, plus `H`, `H(0-7)` and `H/15`, placed as\n Jenkins places them from the job\'s full name. An unbounded `H` in day-of-month\n stays within 1 to 28. Both day fields must match. The macros use `H` (`@daily` is\n `H H * * *`, `@midnight` is `H H(0-2) * * *`), so pass `--dialect jenkins` for a\n Jenkins macro: a bare macro is detected as standard.\n\nOutput: `{ expression, dialect, dialectSource, zone, from, explanation, fields,\nruns: [{ instant, local, offset, dst? }], skipped, skippedTotal, verified }`. `fields` holds what\neach field expanded to, with day-of-week 0 for Sunday in every dialect.\n\nDST: a run time the zone skipped isn\'t listed as a run; it\'s in `skipped`, with a\n`CRON_DST_GAP` warning giving the total. `skipped` lists the first 100 and\n`skippedTotal` counts them all. The walk stops after 5,000 skipped run times (more\nthan one every-second gap hour), warning `CRON_SEARCH_STOPPED` with the last one\nreached, so a schedule that only lands in gaps (`* * 2 ? 3 1#2` in New York) answers\nat once; pass a later `--from` to look further. A run time that happened twice is listed once, at the first,\nwith a `dst` object and a `CRON_DST_OVERLAP` warning. Schedulers differ on both, so\ncheck yours. Fewer runs than `--count` in the next 100 years (or in Quartz\'s listed\nyears) warns `CRON_FEW_RUNS`; `0 0 30 2 *` never runs.\n\nChecks: each run, read back as the wall clock its zone shows then, matches every\nfield again (`cron.rematch`); the runs come after `--from` and in order\n(`cron.order`); `local` is the same instant (`cron.local`); and each skipped time\nreally is in a gap (`cron.gap`). A failure warns `CRON_RUN_MISMATCH`. The\nexplanation\'s wording isn\'t checked, and says so (`UNVERIFIED`): it\'s built from the\nsame fields the run times come from, and the run times are what\'s checked.\n\n### `toil util md`\n\nConverts a document between Markdown and the rich-text formats the Atlassian\nareas send: Jira wiki markup (Jira Data Center), Atlassian Document Format\n(Jira Cloud, Confluence Cloud) and Confluence storage format (Confluence Data\nCenter). One side is always Markdown. Every result is checked by converting it\nback, so you\'re told exactly what didn\'t survive.\n\n```bash\ntoil util md description.md --to wiki\ntoil util md page.md --to storage\ntoil util md description.md --to adf --select output\ntoil util md PROJ-142.wiki --from wiki\ntoil util md description.adf.json --from adf\n```\n\nADF input is the document itself, `{ "type": "doc", "version": 1, "content": [...] }`:\nan issue\'s `fields.description` or a comment\'s `body`, not the issue around it.\n\n| Argument / flag | Meaning |\n|-----------------|---------|\n| `[file]` | A file inside the workspace. `-`, or no file and no `--text`, reads stdin |\n| `--text <text>` | The document itself, instead of a file |\n| `--to <format>` | `wiki`, `adf` or `storage`, to convert Markdown into it |\n| `--from <format>` | `wiki`, `adf` or `storage`, to convert it into Markdown |\n\nOver MCP the tool is `util_md`, with `file` or `text` plus `from` or `to`.\n\nOutput:\n\n```json\n{\n "from": "md",\n "to": "wiki",\n "output": "h2. Steps\\n\\n# Open the login page\\n...",\n "lossless": false,\n "losses": [{ "construct": "task list", "at": "line 12", "detail": "Jira wiki markup has no task lists; each task is written as [ ] or [x] text" }],\n "roundTrip": { "blocks": 9, "differences": [] },\n "verified": { "passed": true, "checks": [{ "check": "roundTrip.blocks", "status": "passed", "checked": 9, "failed": 0 }] }\n}\n```\n\n- **`output`** is the converted document: an ADF document object for `adf`,\n text for the others. Markdown output is in one canonical spelling (`-` bullets,\n `*emphasis*`, `**strong**`, fenced code, one line per paragraph).\n- **`losses`** lists every construct that has no equivalent in the target, with\n its position: `line N` in Markdown, wiki markup and storage format, a JSON\n pointer (`/content/6/content/2`) in ADF. Each kind is also an `MD_LOSSY`\n warning. Words are kept wherever there are words to keep: a panel becomes a\n quote, a mention becomes `@name` text, a merged cell is unmerged with the cells\n it covered left empty.\n- **`roundTrip`**: the output is read back and compared with the input, block by\n block, as canonical Markdown. `differences` shows each block that changed, and\n whether a loss explains it. A change no loss explains fails the\n `roundTrip.blocks` check and warns `MD_ROUNDTRIP_MISMATCH`: that\'s a bug in the\n converter, so check the output before you send it.\n- **`lossless`** is true only when nothing was lost and every block came back the same.\n- **ADF output is validated against the ADF JSON schema** (Atlassian\'s\n `@atlaskit/adf-schema`, bundled) before it\'s returned, and storage output is\n read back as XML. Output that fails either is never returned; the command fails\n instead. ADF input the schema refuses is converted as far as it reads, with an\n `ADF_INPUT_INVALID` warning.\n\nReading and writing run in a worker thread, the conversion and the read back each\nwith 10 seconds and 1,024 MB; a 4 MiB document, the input limit, takes under\n4 seconds. A document whose emphasis or brackets would take far longer, or that\nnests past the stack, fails with `TIMEOUT` or `INVALID_INPUT` naming the step and\nthe limit.\n\nWhat Markdown means here: CommonMark plus GFM tables, task lists, strikethrough\nand bare-URL links. Raw HTML (other than `<br>`), link reference definitions and\nfootnotes aren\'t read; they\'re kept as text and reported as losses.\n\nKnown losses, by format:\n\n- **Wiki markup:** no task lists (written as `[ ]` / `[x]` text), no table\n alignment, no link or image titles, lists always start at 1, and a list item is\n one line, so a code block or second paragraph in one is joined with line breaks.\n Underline, colour, sub/superscript, citations, panels, mentions, attachments and\n other macros don\'t come back into Markdown. Text such as `(y)` that Jira shows as\n an emoticon, and a URL written as text, which Jira links, are reported too.\n- **ADF:** a quote can\'t hold a heading, table, task list or another quote, and a\n list item can\'t hold a heading, quote or table, so those are brought down and\n reported. Inline images become links; explicit left alignment is the default.\n Panels, expands, mentions, emoji, dates, statuses, smart links, decisions,\n attachments, layouts, extensions and merged cells don\'t come back.\n- **Storage format:** a list mixing tasks and ordinary items becomes a task list.\n Info, note, tip and warning panels, expand, layouts, page and user links,\n attachments, emoticons, colour, merged cells and other macros don\'t come back.\n Only XML\'s entities and HTML\'s common named ones (`&nbsp;`, `&mdash;` and so on)\n are read; any other is refused with `INVALID_INPUT`, as is XML that isn\'t\n well-formed, with its line and column.\n\nTo send the result, pass it to the area\'s own command: wiki markup as\n`toil jira issue create --description`, storage format as\n`toil confluence page create --body` (or `confluence-cloud`), and ADF as\n`fields.description` in a `toil jira-cloud issue create --input-file`. How each product\'s own renderer displays it hasn\'t\nbeen checked against a live instance.\n### `toil util openapi`: read an API description before calling it\n\nThree commands that read an OpenAPI 3.0, 3.1 or 3.2 or Swagger 2.0 document, in JSON\nor YAML, so you can call an endpoint right the first time, usually through\n`toil <area> api`. The document is a file in the workspace, `-` for stdin, or\n`--text` (`file` or `text` over MCP). Nothing is fetched: the official schemas\neach version is checked against are bundled.\n\n```bash\ntoil util openapi list jira-platform.json --tag Issues\ntoil util openapi list github.yaml --path pulls\ntoil util openapi show jira-platform.json --operation createIssue\ntoil util openapi show bitbucket.json --method POST --path /repositories/{workspace}/{repo_slug}/pullrequests --depth 1\ntoil util openapi example jira-platform.json --operation createIssue\ntoil util openapi example github.yaml --operation pulls/get --response 200\n```\n\n| Flag | Meaning |\n|------|---------|\n| `[file]` | The document: a file in the workspace, or `-` (or nothing) for stdin |\n| `--text <text>` | The document itself, instead of a file |\n| `--tag <tag>` | `list`: only operations with this tag (any case) |\n| `--path <text>` | `list`: only operations whose path contains this text. `show` and `example`: the path exactly as the document writes it, with `--method` |\n| `--operation <operationId>` | `show`, `example`: the operation, by its operationId |\n| `--method <method>` | `show`, `example`: the method, with `--path`, for an operation with no operationId |\n| `--depth <n>` | `show`: how many `$ref`s deep to expand schemas (default 3, at most 20) |\n| `--response <status>` | `example`: build that response\'s body (`200`, `201`, `default`) instead of the request body |\n| `--content-type <type>` | `example`: which of the body\'s content types (default: the first JSON one) |\n\nIn Git Bash on Windows, leave the leading `/` off `--path`\n(`--path repos/{owner}/{repo}/pulls`): the shell rewrites `/repos/...` into a file\npath. Both forms match.\n\n- **`list`** returns `{ document, count, operations: [{ method, path, operationId,\n summary, tags, deprecated }] }`.\n- **`show`** returns `{ document, operation, parameters, requestBody, responses,\n call, expansion }`. Each parameter has `name`, `in` (path, query, header, cookie),\n `required` and `schema`. The request body and each response have `contentTypes`,\n the `contentType` the `schema` is for (the first JSON one), and `schemaPointer`.\n Swagger 2.0\'s `body` and `formData` parameters come out as the request body, so\n both versions have one shape.\n- **Expanded schemas:** `$ref`s are replaced by what they point at, `--depth` refs\n deep, and an expanded one says where it came from in `x-toil-ref`. One left in\n place says why in `x-toil-stop`: `depth`, `circular` (it loops back), `external`\n (another file or a URL) or `broken`. `expansion.stopped` counts each. Expansion\n builds at most 250,000 objects and arrays per call (`expansion.nodes`) and copies\n at most 4,000,000 characters of the document\'s text (`expansion.chars`), since refs\n can fan out and each copies its whole target (three properties each referring to\n the next, twenty deep, is 3^20 copies). Past that, the rest stay in place as\n `depth`, `expansion.truncated` is true and an `OPENAPI_EXPANSION_TRUNCATED` warning\n says so. `example` generates at most 250,000 values, no more array items than\n that leaves room for, strings of at most 10,000 characters each, and at most 1,000,000\n characters in all, a document\'s own `const` and `enum` values included (a\n `minLength` or a pattern\'s `{n}` past that is cut; any value past the total is null). A cut-short example fails `example.valid` with\n `OPENAPI_EXAMPLE_TRUNCATED` and isn\'t validated. In 3.0 and\n Swagger 2.0 a `$ref`\'s sibling keys are dropped, as the spec says. From 3.1\n they\'re kept, over the target\'s keys.\n- **`example`** returns `{ document, operation, body, status, contentType,\n schemaPointer, example }`. The example is the smallest body the schema accepts:\n required properties only (read-only ones left out of a request, write-only ones\n out of a response), the first enum value, the lowest number in range, a string in\n the right format with placeholder values (`you@example.com`, `api.imagile.dev`),\n the first branch of a `oneOf`. It\'s minimal, not complete: Jira\'s `createIssue`\n gives `{}`, because its schema requires nothing. Use `show` to see the fields you\n want to add.\n\n#### Calling the endpoint with `<area> api`\n\n`show`\'s `call` is the operation as `<area> api` takes it: `method`, `path` (the\nserver\'s base path plus the operation\'s, with `{name}` for each of\n`pathParameters`), `query` (each required query parameter as `name=<name>`),\n`bodyFile`, `contentType` (set only when it isn\'t `application/json`), whether it\n`writes`, and the CLI line. Over MCP the same fields are `<area>_api`\'s inputs.\n\n```bash\ntoil util openapi show jira-platform.json --operation editIssue --select call\n# { "method": "PUT", "path": "/rest/api/2/issue/{issueIdOrKey}", "bodyFile": "body.json", "writes": true,\n# "cli": "toil <area> api PUT /rest/api/2/issue/{issueIdOrKey} --body-file body.json --allow-write", ... }\ntoil util openapi example jira-platform.json --operation editIssue --select example\ntoil jira api PUT /rest/api/2/issue/ABC-123 --body-file body.json --allow-write\n```\n\nSave the example as `body.json`, fill in the placeholders, and put the area the\ndocument describes for `<area>`. The path is relative to the connection\'s\n`baseUrl`: when `baseUrl` already ends with the server\'s base path (`/2.0` for\nBitbucket Cloud\'s), leave that part off. `call.unsupported` lists required header and\ncookie parameters, which `<area> api` doesn\'t send. `call` is null for a method it\ndoesn\'t send (OPTIONS, TRACE, QUERY).\n\n#### What every command checks\n\nEach one reads the whole document and checks it before answering, and\n`data.verified` says what it checked:\n\n| Check | What it is | Warning when it fails |\n|-------|------------|-----------------------|\n| `document.schema` | The document against the official schema for its version (Swagger 2.0, OpenAPI 3.0, 3.1 or 3.2), bundled. Every problem is in `document.problems` by JSON pointer (`/paths/~1pets/get/responses`), at most 50, with `problemCount` | `OPENAPI_INVALID` |\n| `refs.resolve` | Every local `$ref` points at something. Broken ones are in `document.refs.broken` as `{ at, ref }`, `at` being where the `$ref` sits | `OPENAPI_REF_BROKEN` |\n| `operations.uniqueIds` | No operationId is used twice | `OPENAPI_DUPLICATE_OPERATION_ID` |\n| `operations.pathParameters` | Every `{name}` in a path is declared as a path parameter | `OPENAPI_PATH_PARAMETER_MISSING` |\n| `example.valid` | `example` only: the generated body validates against its own schema, `$ref`s and all, before it\'s returned | `OPENAPI_EXAMPLE_INVALID` |\n| `input.complete` | The whole file was read | `INPUT_INCOMPLETE` |\n\nAn invalid document is still listed and shown, since real vendor documents aren\'t\nalways valid, but `verified.passed` is false. `document.refs.circular` lists each\nloop of references (a recursive schema), which is legal; nothing follows one\nforever. What can\'t be checked is reported, never assumed:\n\n- Checking the document against its schema gets 15 seconds and 1,536 MB, enough for a\n vendor spec of 13 MB, which takes about 4 seconds. Validating an example, and\n running the document\'s own `pattern`s, each get 2 seconds and 256 MB.\n A document too big to finish, a schema that branches too much (a diamond of\n `anyOf`s), a pattern that backtracks without end (`^(a+)+$`), or a document too\n deep for the stack leaves `document.schema`, `example.valid` or `example.patterns`\n unchecked, with which limit it hit (`UNVERIFIED`). So does a Node run with\n `--permission` and no `--allow-worker`.\n A document nested more than 256 levels is refused (`INVALID_INPUT`).\n- A YAML document is read in a worker thread with the same 15 seconds and 1,536 MB:\n YAML takes several times JSON\'s memory. Past either limit the command fails with\n `TIMEOUT` or `INVALID_INPUT` naming it; the same document as JSON reads in a fraction\n of both.\n- A `$ref` to another file or a URL isn\'t followed (`refs.external`, `UNVERIFIED`),\n and an example whose schema reaches one isn\'t validated.\n- The 3.1 and 3.2 schemas leave Schema Objects to the JSON Schema 2020-12 dialect,\n which isn\'t checked (`document.schemaObjects`, `UNVERIFIED`). Swagger 2.0 and 3.0\n documents are checked all the way down.\n- Some schemas have no value that satisfies them (two `allOf` branches that\n disagree, a property required and forbidden at once). The example is returned\n anyway, with `example.valid` failed at the pointer that doesn\'t fit, so you fill\n that value in by hand.\n\nA document that isn\'t an object, has no `openapi` or `swagger` field, declares a\nversion these commands don\'t read (OpenAPI 4, Swagger 1.2), or isn\'t valid JSON or\nYAML fails with `INVALID_INPUT`. So does an operation that isn\'t there (the fix names\nclose operationIds), `example` on an operation with no request body (pass\n`--response`), and a status or content type the operation doesn\'t list.\n\n### `toil util c4 render`, `toil util c4 mermaid`, `toil util c4 d2`\n\nOne view of a C4 architecture model: `render` draws it as SVG, `mermaid` writes it\nas Mermaid\'s C4 syntax (GitHub draws a ```` ```mermaid ```` block inline), and `d2`\nwrites it as D2 text. `render` lays the diagram out itself, with a layered layout\nmade for C4 views: people on the top row, the scope\'s children together inside\ntheir dashed boundary, and each relationship\'s label placed clear of the boxes.\nNothing is installed or run, and nothing goes over the network.\n\n```bash\ntoil util c4 render docs/c4/bookshop.c4.json --view containers --out containers.svg\ntoil util c4 mermaid docs/c4/bookshop.c4.json --view context\ncat model.json | toil util c4 d2 - --view components\n```\n\n| Flag | Meaning |\n|------|---------|\n| `[file]` | A JSON file holding the model, inside the workspace, or `-` (or nothing) for stdin |\n| `--text <text>` | The model itself, as a JSON string, instead of a file. Over MCP, `file` or `text` |\n| `--view <key>` | The view to draw. It can be left out when the model has only one |\n| `--out <file>` | `render` only: write the SVG to this new file inside the workspace instead of returning it. toil never overwrites a file |\n\nThe model:\n\n```json\n{\n "title": "Online bookshop",\n "people": [{ "id": "customer", "name": "Customer", "description": "Buys books" }],\n "systems": [{\n "id": "bookshop", "name": "Online Bookshop", "description": "Sells books at bookshop.imagile.dev",\n "containers": [\n { "id": "web", "name": "Web shop", "technology": "React",\n "components": [{ "id": "cart", "name": "Cart", "technology": "TypeScript" }] },\n { "id": "db", "name": "Database", "technology": "PostgreSQL", "database": true }\n ]\n }, { "id": "payments", "name": "Payment provider", "external": true }],\n "relationships": [{ "source": "customer", "destination": "web", "description": "Buys books using", "technology": "HTTPS" }],\n "views": [\n { "key": "context", "type": "systemContext", "scope": "bookshop" },\n { "key": "containers", "type": "container", "scope": "bookshop" },\n { "key": "components", "type": "component", "scope": "web", "include": ["*", "payments"] }\n ]\n}\n```\n\n- **Elements** are people and software systems at the top, containers inside a\n system, and components inside a container. Each has an `id`, a `name`, and\n optionally a `description`, a `technology` (containers and components) and\n `external: true`, which draws it grey. A container with `database: true` is drawn\n as a cylinder. Ids start with a letter and hold only letters, digits and\n underscores, and are unique across the whole model.\n- **Relationships** join any two elements, at any level: `source`, `destination`,\n and optionally `description` and `technology`.\n- **Views** have a `key`, a `type` (`systemContext`, `container` or `component`), a\n `scope` (a system for the first two, a container for `component`), an optional\n `title`, and an optional `include` list of ids. `"*"` in it stands for the default\n set, which is also what you get with no `include`: for `systemContext`, the scope\n and every person and system related to it; for `container`, the scope\'s\n containers inside a dashed boundary and what they relate to; for `component`, the\n scope\'s components and what they relate to.\n- A relationship is drawn between the nearest elements a view shows, so one between\n two containers shows up between their systems in a system context view. Model\n relationships at the most detailed level you know. One that ends on a view\'s own\n boundary from outside can\'t be drawn there; a `C4_RELATIONSHIP_NOT_DRAWN` warning\n in `meta.warnings` names it, unless that outside element already has a drawn\n relationship into the boundary.\n\nOutput: `{ view, type, title, elements, relationships, verified, format, svg }` for\n`render`, where `elements` lists the ids drawn and `relationships` counts the arrows.\nWith `--out`, `{ file, bytes }` take the place of `svg`, and `file` is the absolute\npath written. `mermaid` and `d2` return `text` in place of `svg`.\n\n`render` lays the view out down the page: arrows leave a box from its bottom, run\nstraight through any row they pass, and enter their target from the top, so they\nbend only in the gaps between rows. It checks its own drawing before returning it,\nand `data.verified` lists each check:\n\n| Check | What held |\n|-------|-----------|\n| `input.complete` | The whole file was read (unchecked for stdin and `--text`) |\n| `boxes.apart` | No two boxes overlap |\n| `children.inBoundary` | Every child is inside its dashed boundary, and nothing else is drawn over it (views with a boundary only) |\n| `edges.touchBoxes` | Every arrow starts on its source\'s border and ends on its target\'s |\n| `edges.clearOfBoxes` | No arrow passes behind a box it doesn\'t join |\n| `labels.clearOfBoxes` | No label covers a box |\n| `svg.wellFormed` | The SVG parses as XML and holds no character XML forbids. A control character in the model\'s text (other than tab and line breaks), U+FFFE, U+FFFF or a lone surrogate is drawn as U+FFFD |\n| `text.width` | Always `approximated`: text is measured with Helvetica\'s widths, which Arial shares |\n\nEach check that fails is one `C4_LAYOUT_CHECK` warning in `meta.warnings` naming\nthe first boxes or arrow involved and how many failed, and the first five are in\n`verified`, so a bad drawing is never returned without saying so. `mermaid` and\n`d2` check their own text instead: every element declared once (`text.elements`)\nand one line per arrow (`text.relationships`), failing as `C4_TEXT_CHECK`. Whether\nthe text draws is up to whatever renders it, and is reported as unchecked\n(`text.renders`, `UNVERIFIED`).\n\nLimits, each an `INVALID_INPUT` past it, before any work grows with it:\n\n- The model\'s JSON is at most 4 MiB.\n- A model holds at most 1,000 elements (people, systems, containers and components\n together), 2,000 relationships and 100 views.\n- `render` draws at most 100 boxes and 250 arrows in one view. Draw fewer with the\n view\'s `include` list, or split the view; `mermaid` and `d2` write a view of any\n size the model allows.\n\nThe layout runs in a worker thread with a 2 s deadline and 256 MB, past which it\'s\nstopped with `TIMEOUT`, or `INVALID_INPUT` for the memory; at the limits above it\ntakes well under a second and about 40 MB. Past about\n25 boxes, arrows cross more often and the drawing grows tall.\n\nA model with mistakes fails with `INVALID_INPUT` before anything is drawn. The\nmessage names each problem by its path in the model, such as\n`relationships[2].destination: no element has the id "warehose"`, and\n`error.details` lists them all. An unknown `--view` lists the keys the model has.\n\nA sample model, an online bookshop with all three views, is\n`docs/c4/bookshop.c4.json` in toil\'s source, and `docs/c4/busy.c4.json` is a busier\nview of 25 boxes.\n\n### `toil util owi map`\n\nMaps the output of toil\'s own work item and pull request commands to Open Work\nItems (OWI 0.2), the model in `docs/owi/spec.md` in toil\'s source, with its JSON\nSchema beside it in `docs/owi/schema.json`. It composes: each tracker is read by its own command,\nand this reads what they printed, whether piped, saved to a file, or appended one\nenvelope a line.\n\n```bash\ntoil jira issue search --jql "sprint in openSprints()" --fields "summary,status,issuetype,Story Points,Sprint" | toil util owi map\ntoil util owi map sprint-42.jsonl\ntoil util owi map changelog.json --key PAY-104\ntoil util owi map batch.json --field estimate=Custom.TeamPoints --field estimateUnit=points\ntoil util owi map issue.json --command "github issue get"\ntoil util owi map prs.jsonl --key-pattern "PAY-{n}=corp-jira" --author-kind release-bot=BOT\n```\n\n| Argument / flag | Meaning |\n|-----------------|---------|\n| `[file]` | A file inside the workspace. `-`, or no file and no `--text`, reads stdin |\n| `--text <text>` | The input itself, instead of a file |\n| `--command <name>` | The command whose data the input is, when it holds `data` without its envelope (`"jira issue search"`) |\n| `--key <key>` | The item a history belongs to, when its output doesn\'t say: `PAY-104`, or `imagile/payments-web#44` (a bare `44` takes the envelope\'s owner and repo) |\n| `--field <name=field>` | Point an OWI field at a field of your own, repeatable: `estimate`, `estimateUnit` (`points`, `hours` or `days`), `priority`, `type`, `team`, `dueDate` or `iteration`; and for GitHub without a board, `estimateLabel` (`size/{n}`) and `iterationDays` |\n| `--key-pattern <pattern=connection>` | Where work item keys in a pull request\'s title, branch and description point, repeatable, with `{n}` where the number is: `PAY-{n}=corp-jira`, `AB#{n}=corp-ado` |\n| `--author-kind <id=KIND>` | Set a pull request author\'s kind by hand, repeatable: `release-bot=BOT`, with `KIND` one of `HUMAN`, `AGENT` or `BOT`. It wins over every other signal |\n\nOver MCP the tool is `util_owi_map`, with `file` or `text`, and `command`, `key`,\n`field` (a list of `name=field`), `keyPattern` (a list of `pattern=connection`)\nand `authorKind` (a list of `id=KIND`).\n\n**What it reads**, by the command each envelope\'s `meta.command` names:\n\n- **Jira and Jira Cloud:** `issue search` and `issue get` (one key or several) for items,\n `issue history` for history.\n- **Azure DevOps and Azure DevOps Services:** `work-item get` and `work-item get-many` for items, `work-item history`\n for history, and `work-item iterations` for iteration dates. `work-item search`\n returns ids only and is skipped: map `work-item get-many` for those ids instead.\n- **GitHub:** `issue list`, `issue search` and `issue get` for issues,\n `project items` for the board\'s status, estimate and iteration, and\n `issue history` for history. Where no board gives a value, the issue\'s\n milestone is its iteration, a `points: N` label its estimate, and "Blocked by\n #n" or "Depends on #n" in its body a `blocks` link. Pull requests in an issue\n list or on a board are left out of the items with a warning.\n- **Pull requests:** `pr list` and `pr get` of `github`, `bitbucket`,\n `bitbucket-cloud`, `ado` and `ado-cloud`, as changes. A list is enough to rank\n what is open; `pr get --include reviews,checks,commits,files` adds what a list\n lacks, and a pull request in both is one change with the get\'s fields.\n\nPass one envelope, a JSON array of them, or one a line (`>>` appends each command\'s\noutput to one file). A Jira changelog and a GitHub timeline don\'t name their issue,\nso give `--key`, or wrap each as `{ "key": "PAY-104", "history": <envelope> }` in a\nfile holding several. Output from any other command is refused with\n`INVALID_INPUT` naming the ones that map.\n\nOutput:\n\n```json\n{\n "owi": "0.2",\n "count": 1,\n "items": [{\n "owi": "0.2",\n "id": "corp-jira:PAY-101",\n "source": { "area": "jira", "connection": "corp-jira", "key": "PAY-101", "command": "jira issue get" },\n "url": "https://jira.imagile.dev/browse/PAY-101",\n "type": "STORY", "typeName": "Story",\n "title": "Tokenise card numbers at the edge",\n "status": "In Progress", "statusCategory": "IN_PROGRESS",\n "estimate": { "value": 5, "unit": "points", "field": "Story Points" },\n "iteration": { "id": "42", "name": "Sprint 42", "path": null, "start": "2026-10-05T09:00:00.000Z", "end": "2026-10-16T17:00:00.000Z", "state": "current" },\n "parent": "corp-jira:PAY-100",\n "links": [{ "type": "blocks", "direction": "outward", "target": "corp-jira:PAY-102", "name": "blocks" }],\n "history": { "transitions": [{ "from": "To Do", "to": "In Progress", "fromCategory": "TODO", "toCategory": "IN_PROGRESS", "at": "2026-10-06T09:15:00.000Z", "by": { "id": "jsmith", "name": "J. Smith", "email": null } }], "iterations": [] },\n "unmapped": [],\n "native": { "jira issue get": { "key": "PAY-101", "fields": { "...": "..." } } }\n }],\n "changes": [],\n "histories": [],\n "unmapped": {},\n "skipped": [],\n "verified": { "passed": true, "checks": [{ "check": "items.schema", "status": "passed", "checked": 1, "failed": 0 }] }\n}\n```\n\n(Each item has every field in the spec; this one is shortened.) `count` is the\nnumber of items. A pull request is one of `changes`:\n\n```json\n{\n "owi": "0.2",\n "id": "github:imagile/payments-web#51",\n "source": { "area": "github", "connection": "github", "key": "imagile/payments-web#51", "command": "github pr get" },\n "repo": "imagile/payments-web",\n "title": "Retry the address lookup once",\n "branch": { "source": "claude/address-retry", "target": "main" },\n "state": "OPEN",\n "author": { "id": "ada-dev", "name": null, "email": null },\n "authorKind": "AGENT", "authorKindSource": "trailer", "authorKindSignal": "Co-Authored-By: Claude <you@example.com>",\n "reviewers": [], "reviews": [],\n "checks": "FAILING", "checksAt": "2026-10-09T08:10:00.000Z",\n "mergeable": true,\n "size": { "files": 2, "additions": 71, "deletions": 5 },\n "workItems": [],\n "created": "2026-10-08T09:00:00.000Z", "firstReviewAt": null, "approvedAt": null, "mergedAt": null,\n "unmapped": []\n}\n```\n\n- **`authorKind`** is `HUMAN`, `AGENT` or `BOT`, and `authorKindSource` says what\n set it, strongest first: an `override` (`--author-kind`), the `account` (GitHub\'s\n Bot type, a coding agent\'s account, a Bitbucket service account), an agent\'s\n Co-Authored-By `trailer` on a commit, an agent\'s `branch` prefix (`claude/`,\n `copilot/`, `codex/`), or `default` (`HUMAN`, nothing said otherwise).\n- **`workItems`** are the OWI ids the title, branch and description name: GitHub\'s\n own `#12` and Azure DevOps\' own `#2302` with no setup, and everything else by\n `--key-pattern`.\n- **`checks`** is `PASSING`, `FAILING`, `PENDING` or `NONE`, rolled up from the\n checks on the latest commit; null, with the reason in `unmapped`, when the input\n didn\'t hold them. The same goes for reviews, mergeability and size: each says\n which command fills it.\n\n- **`id`** is `<connection>:<native key>`, so items from two Jira sites never\n collide. Links, parents and children use the same ids.\n- **`statusCategory`** is `TODO`, `IN_PROGRESS`, `DONE` or `UNKNOWN`: from Jira\'s\n status category, Azure DevOps\' default states, and a GitHub board\'s Status\n options. A status with no known category is `UNKNOWN`, with an\n `OWI_UNKNOWN_STATE` warning naming it.\n- **`estimate`** comes from each tracker\'s default field: Story Points or Story\n point estimate in Jira (by the name the connection registers, never a fixed\n `customfield_` id), then the original estimate in hours; StoryPoints, Effort or\n Size in Azure DevOps, then OriginalEstimate; a board number field named\n Estimate, Size or Story Points in GitHub, else a label such as `points: 3`\n (`field` is then `label:points: 3`). `field` says which. Teams with a field of\n their own point `estimate` at it with `--field`, the same keys a dossier\'s\n `fields` uses; a GitHub team with its own estimate labels names them with\n `--field estimateLabel=size/{n}`.\n- **`iteration`** on a GitHub issue with no board value is its milestone: the\n due date is the end, and the previous milestone\'s due date the start (14 days\n before the end for the first, or `--field iterationDays=10` for every one).\n- **`unmapped`**, on each item, lists every field the record couldn\'t fill and\n why: a field `jira issue search` wasn\'t asked for, an iteration whose dates need\n `ado work-item iterations`, a GitHub issue with no milestone and no board. `data.unmapped`\n counts them by field, and an `OWI_UNMAPPED` warning sums them up. Nothing is\n guessed.\n- **`histories`** holds histories whose item wasn\'t in the input, by id, so they\n can be joined to items read earlier. **`skipped`** lists each document that\n wasn\'t mapped (a failed call, `work-item search`), each also an `OWI_SKIPPED` warning.\n- **`native`** keeps every source record as it came, keyed by command.\n- **`verified`:** every item, every history in `histories` and every change is\n validated against `docs/owi/schema.json` (`items.schema`, `histories.schema`,\n `changes.schema`) before it is returned; a failure is an `OWI_SCHEMA_INVALID` warning naming the item and the\n JSON pointer. The validation runs in a worker with a 2 s deadline per item, and\n one that can\'t finish is unchecked, never passed. `input.complete` checks the\n whole file was read.\n\nAt most 5,000 items, and 5,000 changes, are mapped in one call; past that the rest are left out with\nan `OWI_ITEMS_CAPPED` warning, so map them in another call. Input is at most\n64 MiB.\n\n### `toil util owi similar`\n\nFinds likely duplicate work items among Open Work Items, offline and deterministic:\nno model, no network, and the same answer every time. It reads what\n`toil util owi map` printed and asks no tracker itself, so it composes with any\nsearch. **Run it before filing or proposing a new item**, and before triaging one:\n`--query` with the title you were about to file says whether it already exists, in\nJira, Azure DevOps or GitHub.\n\n```bash\ntoil jira issue search --jql "project = PAY" | toil util owi map | toil util owi similar --query "Card payments time out at checkout"\ntoil util owi similar --input-file items.owi.json --item corp-jira:PAY-101 --limit 5\ntoil util owi similar --input-file items.owi.json --pairs --threshold 0.6\ntoil util owi similar items.owi.json --pairs --fields title,body\n```\n\n| Argument / flag | Meaning |\n|-----------------|---------|\n| `[file]`, `--input-file <path>` | The OWI records: a file inside the workspace. `-`, or no file and no `--text`, reads stdin |\n| `--text <text>` | The records themselves, instead of a file |\n| `--query <text>` | Rank every item against this text |\n| `--item <id>` | Rank the set against one of its items, by OWI id (`corp-jira:PAY-101`) |\n| `--pairs` | List likely duplicate pairs across the whole set, so items from different trackers are compared with each other |\n| `--limit <n>` | The most matches or pairs to return (default 10, up to 1000) |\n| `--threshold <score>` | The lowest score returned, 0 to 1 (default 0.35) |\n| `--fields <list>` | What to compare, separated by commas: `title`, `body`, `labels`, `parent` and `links` (default all) |\n\nAsk exactly one of `--query`, `--item` and `--pairs`. Over MCP the tool is\n`util_owi_similar`, with `file` or `text`, one of `query`, `item` and `pairs`, and\n`limit`, `threshold` and `fields`.\n\n**What it reads:** the envelope `util owi map` printed, its `data`, a JSON array of\nOWI records (as Toil UI\'s cache holds them), or one record a line. A record needs an\n`id` and a `title`; one without either is skipped, listed in `data.skipped` and\nwarned about (`OWI_SIMILAR_SKIPPED`). Output from any other command is refused with\n`INVALID_INPUT`: map it first. An id that appears twice is read once\n(`OWI_SIMILAR_DUPLICATE_ID`).\n\nOutput, for `--item corp-jira:PAY-210 --limit 1`:\n\n```json\n{\n "mode": "item",\n "method": "Lexical similarity: BM25-weighted shared terms in titles and bodies, title character trigrams, and small boosts for shared labels, the same parent and a direct link. It measures shared words, not meaning, so a duplicate written in entirely different words scores low.",\n "fields": ["title", "body", "labels", "parent", "links"],\n "threshold": 0.35, "limit": 1,\n "query": null,\n "item": { "id": "corp-jira:PAY-210", "title": "Card payments time out at checkout", "source": { "area": "jira", "connection": "corp-jira", "key": "PAY-210", "command": "jira issue search" }, "url": "https://jira.imagile.dev/browse/PAY-210" },\n "items": 39, "count": 4,\n "matches": [{\n "id": "github:imagile/payments-web#51",\n "title": "Checkout times out when paying by card",\n "source": { "area": "github", "connection": "github", "key": "imagile/payments-web#51", "command": "github issue list" },\n "url": "https://ghe.imagile.dev/imagile/payments-web/issues/51",\n "score": 0.7211,\n "why": {\n "summary": "title terms checkout, time, card; body terms pay, 504, release, spinner, timeout, gateway; titles 72% alike by trigram; shared label checkout.",\n "titleTerms": ["checkout", "time", "card"],\n "bodyTerms": ["pay", "504", "release", "spinner", "timeout", "gateway"],\n "trigram": 0.7234,\n "labels": ["checkout"], "parent": null, "link": null, "titleOnly": false,\n "parts": { "terms": 0.4702, "trigram": 0.217, "labels": 0.0338, "parent": 0, "link": 0 }\n }\n }],\n "pairs": [], "search": null,\n "titleOnly": 19, "skipped": [],\n "verified": { "passed": true, "checks": [{ "check": "score.parts", "status": "passed", "checked": 1, "failed": 0 }, { "check": "score.meaning", "status": "approximated", "checked": 0, "failed": 0, "detail": "\u2026" }, { "check": "input.complete", "status": "passed", "checked": 1, "failed": 0 }] }\n}\n```\n\n`--pairs` returns `pairs` instead, each `{ score, a, b, why }` with `a` the lower id,\nand `search`: how many pairs were `compared`, and `skippedFeatures` (below).\n\n**How it scores**, so `why` can say exactly what drove each score:\n\n- **Terms (`titleTerms`, `bodyTerms`):** titles and bodies (Markdown, Jira wiki\n markup, HTML and ADF, read as plain text without their URLs) become lowercase\n words, with common English words dropped and plurals, `-ed` and `-ing` stemmed,\n each weighted by BM25 over the set, a title word worth twice a body word. Two\n items are compared by the cosine of those weights; a query by how much of its\n weight an item covers, a word in the title counting fully and one only in the\n body at most 0.7.\n- **Trigrams (`trigram`):** the character trigrams of the titles\' words, which\n catch typos and word forms the terms miss (`Recipt` and `Receipt`).\n- **Boosts (`labels`, `parent`, `link`):** up to 0.08 for shared labels (a rarer\n label counts more), 0.05 for the same parent and 0.1 for a direct link. Together\n they can\'t reach the default threshold on their own; at a threshold of 0.23 or\n less they can, and `OWI_SIMILAR_LOW_THRESHOLD` says so.\n\nThe score is 0.7 of the terms and 0.3 of the trigrams (all terms when titles aren\'t\nin `--fields`), plus the boosts, capped at 1 and rounded to four places. `parts`\nsays what each added, and they sum to the score. Results score at least the\nthreshold, best first, ties by id.\n\n**What it misses:** it measures shared words, not meaning. Two items that describe\none problem in entirely different words ("checkout hangs" and "payment page never\nloads") score low, which `method` and an `APPROXIMATED` warning say on every call.\nAn item with no body is compared on its title alone (`why.titleOnly`), and\n`OWI_SIMILAR_TITLE_ONLY` names those items: where the tracker holds a body, map them\nfrom a command that returns it. A body is read up to 5,000 terms\n(`OWI_SIMILAR_BODY_CUT`).\n\n**Large sets:** scoring runs in a worker with a 30 s deadline, so tens of thousands\nof items never hold the CLI or the MCP server. `--pairs` finds pairs through the\nterms, trigrams, labels and parents they share, so its work grows with what items\nhave in common, not with the square of the set. On a very large set the commonest\nof those stop being used to find pairs once a fixed budget is spent; `search`\ncounts them, and an `APPROXIMATED` warning says a pair sharing only those wasn\'t\ncompared. At most 50,000 records are scored in one call (`OWI_SIMILAR_CAPPED`), and\ninput is at most 64 MiB.\n\n**`verified`:** `score.parts` checks every returned score lies in 0 to 1 and equals\nits parts. With `--pairs`, `pairs.postings` holds the one shortcut the scorer takes\nto it: each pair\'s score is summed from the terms and trigrams it shares, and every\npair returned is worked out again in full, so the two must agree (where common\nfeatures were skipped, the summed score must not be the larger). A failure is an\n`OWI_SIMILAR_MISMATCH` warning. The same input always gives the same `data`.\n\nFrom a program, `findSimilar(items, request, options)` in `@imagile-dev/toil/api`\nranks OWI records you already hold the same way, in-process (`core.md`, **Using\ntoil from a program**).\n'
140454
+ "util.md": '---\narea: util\ndescription: Local utilities with no connection or network, decoding a JWT, inventorying dependencies from manifests and lockfiles, checked encoding and hashing, decoding certificates and checking a chain, summarising test, SARIF and coverage reports, triaging a large log, scanning for secrets before a commit or post, sizing files and folders before reading them, time zone, duration, business-day and cron arithmetic, comparing versions and ranges for npm, NuGet and Maven, converting Markdown to and from Jira and Confluence formats, reading OpenAPI documents, drawing C4 architecture diagrams from a JSON model, mapping Jira, Azure DevOps and GitHub work items to Open Work Items, and finding likely duplicates among them\n---\n\n# Local utilities (`util`)\n\nCommands that work on what\'s on this machine: a token or version you paste, a file or\nfolder in the workspace (a certificate, a log or an API description), the manifests and lockfiles there, a\nreport a build left behind, a C4 model described in JSON, text you\'re about to commit or post, or a time and a time zone. They aren\'t\nintegrations. There is no server, no connection to add, no `TOIL_UTIL_*`\nvariable, no credential and no `--connection` flag, and none of them sends\nanything over the network. None changes anything: the only file one writes is a\nnew one you name with `--out`, inside the workspace, and it never replaces a\nfile. Verification level: `unit`.\n\n`jwt` and `deps` also have a short path, an alias that does the same thing with\nthe same flags and output:\n\n| Command | Alias | MCP tool |\n|---------|-------|----------|\n| `toil util jwt decode` | `toil jwt decode` | `util_jwt_decode` |\n| `toil util deps scan` | `toil deps scan` | `util_deps_scan` |\n| `toil util deps diff` | `toil deps diff` | `util_deps_diff` |\n| `toil util secrets scan` | none | `util_secrets_scan` |\n| `toil util encode` | none | `util_encode` |\n| `toil util cert` | none | `util_cert` |\n| `toil util report` | none | `util_report` |\n| `toil util log` | none | `util_log` |\n| `toil util size` | none | `util_size` |\n| `toil util time convert` | none | `util_time_convert` |\n| `toil util time duration` | none | `util_time_duration` |\n| `toil util time business-days add` | none | `util_time_business_days_add` |\n| `toil util time business-days diff` | none | `util_time_business_days_diff` |\n| `toil util time cron` | none | `util_time_cron` |\n| `toil util semver compare` | none | `util_semver_compare` |\n| `toil util semver satisfies` | none | `util_semver_satisfies` |\n| `toil util semver sort` | none | `util_semver_sort` |\n| `toil util semver bump` | none | `util_semver_bump` |\n| `toil util md` | none | `util_md` |\n| `toil util openapi list` | none | `util_openapi_list` |\n| `toil util openapi show` | none | `util_openapi_show` |\n| `toil util openapi example` | none | `util_openapi_example` |\n| `toil util c4 render` | none | `util_c4_render` |\n| `toil util c4 mermaid` | none | `util_c4_mermaid` |\n| `toil util c4 d2` | none | `util_c4_d2` |\n| `toil util owi map` | none | `util_owi_map` |\n| `toil util owi similar` | none | `util_owi_similar` |\n\nOver MCP the tools are served without any configuration. `toil mcp --areas util`\nserves just these.\n\n## By job\n\nThe same commands, grouped by what you need them for.\n\n### Reading CI output\n\nWhat a build or a scanner leaves behind, turned into something short enough to read: totals and failures from a report, and the errors that matter from a log thousands of lines long.\n\n- **Summarising a report** (`toil util report`): Turns what CI and scanners write into one JSON summary. JUnit XML (Maven Surefire, Jenkins and Azure DevOps shapes) and TRX become test totals plus each failure with its suite, name, file, line, message and the first lines of its stack. SARIF 2.1.0 becomes findings with rule, level, file and line. lcov and Cobertura become per-file line and branch percentages and the lowest-covered files.\n- **Triaging a log** (`toil util log`): Reads a CI console, a Maven, npm or dotnet build, or a test run, and returns what\'s worth reading: the error and warning lines grouped by signature, with numbers, ids, timestamps and hex replaced so the same complaint counts once. Each group has its count, its first and last line, one sample, and the Java, .NET, Node or Python stack trace that belongs to it.\n\n### Writing for the tools\n\nGetting text into the shape an enterprise tool expects before it\'s sent, so a description, a page or a request arrives the way it was meant.\n\n- **Converting Markdown** (`toil util md`): Turns Markdown into Jira wiki markup (Jira Data Center), Atlassian Document Format (Jira Cloud and Confluence Cloud) or Confluence storage format (Confluence Data Center), and any of those back into Markdown.\n- **Reading an OpenAPI document** (`toil util openapi list`, `toil util openapi show`, `toil util openapi example`): Reads an OpenAPI 3.0, 3.1 or 3.2 or Swagger 2.0 document, so an agent calls an endpoint right the first time: `list` gives every operation, `show` lays one out with each parameter and where it goes, its request and response bodies with `$ref`s expanded, and the exact inputs for `toil <area> api`, and `example` builds the smallest body its schema accepts.\n- **Drawing a C4 architecture diagram** (`toil util c4 render`, `toil util c4 mermaid`, `toil util c4 d2`): Draws one view of a C4 model (a system context, container or component view) from JSON an agent writes: `render` lays it out and returns SVG, people on top and the scope\'s children inside a dashed boundary, checked for overlaps, arrows behind boxes and well-formed XML, and `mermaid` and `d2` write the same view as text for places that draw it themselves, such as a Mermaid block in Markdown on GitHub.\n\n### Reading the trackers as one\n\nWork from Jira, Azure DevOps and GitHub in one shape, so a sprint, a board or a question about the work reads the same whichever tracker holds it.\n\n- **Mapping to Open Work Items** (`toil util owi map`): Turns what the jira, jira-cloud, ado, ado-cloud and github commands print into Open Work Items: one model with a type, a status and its category, people, an estimate with its unit and the field it came from, the sprint, parent and children, links, dates and the history of transitions and sprint moves. A GitHub issue and its project board item become one item. The pull requests of github, bitbucket, bitbucket-cloud, ado and ado-cloud become changes: state, who wrote it (a person, an agent or a bot, and the signal that said so), reviewers, checks, size, the work items it names and its review timeline. Every record is checked against the published schema.\n- **Finding likely duplicates** (`toil util owi similar`): Before filing, proposing or triaging an item, asks whether it already exists: ranks OWI records against some text or one of them, or lists likely duplicate pairs across Jira, Azure DevOps and GitHub. Lexical and deterministic, with no model or network, and every match says why it matched: the shared title and body terms, title trigrams, labels, parent and link.\n\n### Safety\n\nChecks to run before something leaves the machine or gets trusted: a secret in a diff, a certificate chain that won\'t validate, a token\'s claims, and the dependencies a repository ships.\n\n- **Scanning for secrets** (`toil util secrets scan`): Looks for credential-shaped strings before you commit, push or post them: tokens, keys, `password=` values, credentials in URLs, private keys and long random strings. It uses the same rules toil\'s audit log redacts with, plus an entropy check, and exits with 1 when it finds anything, so a hook or a pipeline can stop on it.\n- **Decoding certificates** (`toil util cert`): Decodes a certificate or a chain bundle, PEM or DER: subject, issuer, SANs, serial, how many days it has left, its key, its signature algorithm, its basic constraints and key usage, and its fingerprints, so a TLS failure can be explained from the files. It never connects to the host.\n- **Decoding a JWT** (`toil util jwt decode`): Shows a token\'s header and claims, so you can see who it\'s for, what it grants and when it expires.\n- **Inventorying dependencies** (`toil util deps scan`, `toil util deps diff`): `deps scan` lists every package the workspace\'s npm, NuGet and Maven/Gradle manifests and lockfiles declare, with its version, the file it came from, and whether it\'s direct or transitive, production or dev. That inventory is what the vulnerability and licence commands read, one source per command, so you choose which service sees your dependency list. `deps diff` lists what was added, removed, upgraded or downgraded between two git refs.\n\n### Arithmetic models get wrong\n\nWork that looks simple and is easy to get subtly wrong by reasoning alone: time zones and DST, version ordering, encodings and hashes, and how big a file is before reading it. Each one works the answer out, then checks it a second way.\n\n- **Time zones, durations, business days and cron** (`toil util time convert`, `toil util time duration`, `toil util time business-days add`, `toil util time business-days diff`, `toil util time cron`): Date arithmetic on the time zone data Node already ships: convert a time between zones, read or write an ISO 8601 duration, add or count business days, and list a cron schedule\'s next run times.\n- **Comparing versions** (`toil util semver compare`, `toil util semver satisfies`, `toil util semver sort`, `toil util semver bump`): Compare, sort and bump versions, and check them against ranges, in the grammar of the ecosystem they come from: npm (SemVer 2.0.0 and npm\'s ranges, the default), NuGet (up to four parts, interval notation) or Maven (Maven\'s own ordering, where `1.0.0.Final` is `1` and `SNAPSHOT` comes before the release).\n- **Encoding, decoding and hashing** (`toil util encode`): Base64, base64url, hex, URL components and form values, in either direction, and a file\'s SHA-256, SHA-1 or MD5 hash.\n- **Sizing before reading** (`toil util size`): Tells an agent how much a file or folder will cost to read. For a file it gives bytes, lines, an estimated token count, and an outline: functions, classes and methods with their line ranges for TypeScript, JavaScript, Python, C#, Java and Go, headings for Markdown, and top-level keys for JSON and YAML, so the agent reads only the lines it needs. For a folder it gives a tree of totals, largest first, and names the largest files.\n\n## Commands\n\n### `toil util jwt decode`\n\nDecodes a JWT\'s header and claims **without verifying it**. There\'s no key and no\nnetwork call, and nothing here says whether the token is valid, expired or trusted.\n\n```bash\ntoil util jwt decode eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJhYmMxMjM0NSJ9.c2ln\necho "$TOKEN" | toil util jwt decode -\n```\n\n| Argument | Meaning |\n|----------|---------|\n| `<token>` | The token, `header.payload.signature`. `-` reads it from stdin, which keeps it out of the process list and your shell history; one trailing line ending is dropped |\n\nOutput: `{ header, payload, signature }`, the header and claims as parsed JSON and\nthe signature segment as the text it is.\n\n- A token that isn\'t three dot-separated parts (an encrypted 5-part JWE, say) fails\n with `INVALID_INPUT`, `Invalid JWT: expected 3 dot-separated parts`.\n- A header or payload that doesn\'t decode to JSON fails with `Invalid JWT: header is\n not valid JSON` (or `payload`). A `Bearer ` prefix gives this error too, so strip it.\n- The decoding is lenient, as it has always been. A segment that is JSON but not an\n object (`null`, a number) comes back as it is. Characters outside base64url are\n skipped. Invalid UTF-8 shows as `\uFFFD`. Whitespace in a token passed as an argument\n is kept, so a trailing newline ends up in `signature`.\n\nThe token goes nowhere but the decoder. toil doesn\'t log it, and no error message\nrepeats it.\n\n### `toil util deps scan`\n\nThe dependency inventory of the workspace, from its manifests and lockfiles. It\nreads files only and needs no git. It must be inside a git repository, though, or it\nfails with `Not inside a git repository. deps commands require a git repo root.`\n\n```bash\ntoil util deps scan\ntoil util deps scan --ecosystem npm --include-transitive --include-dev\ntoil util deps scan | toil osv vulns\n```\n\n| Flag | Meaning |\n|------|---------|\n| `--ecosystem <ecosystem>` | `npm`, `nuget`, `maven` or `all` (default). Any other value matches nothing and scans nothing |\n| `--include-transitive` | Include transitive dependencies (left out by default) |\n| `--include-dev` | Include dev and test dependencies (left out by default) |\n\nWhich files it reads:\n\n- **Which files:** every file in the workspace that `git ls-files --cached --others\n --exclude-standard` would list. That\'s tracked files plus untracked ones `.gitignore`\n and `.git/info/exclude` don\'t cover. A nested repository isn\'t walked into. Your\n global git excludes file isn\'t read, so a file only it ignores is scanned. An\n ignore file that exists but can\'t be read applies no rules, with a\n `GITIGNORE_UNREADABLE` warning naming it and the fix.\n- **npm:** `package.json` (not under `node_modules`), with the first of\n `package-lock.json` (v2 or later), `yarn.lock` (v1) or `pnpm-lock.yaml` beside it.\n A `package-lock.json` with no packages falls back to `package.json`.\n- **NuGet:** `.csproj`, `.fsproj`, `.vbproj`, `packages.config` and\n `Directory.Packages.props`, with a `packages.lock.json` in the same folder. Project\n files that share one lock file count once. A project with no version on a\n `PackageReference` takes it from the nearest `Directory.Packages.props`, up to 10\n folders up.\n- **Maven/Gradle:** `pom.xml`, `build.gradle` and `build.gradle.kts`, with a\n `gradle.lockfile` beside them.\n\nA lockfile wins over its manifest. Packages are de-duplicated on ecosystem, name,\nversion and source file. A manifest that can\'t be read is skipped. One that exists\nbut can\'t be read (a link out of the workspace, say) also gets a\n`DEPS_FILE_SKIPPED` warning in `meta.warnings`. That warning is the only check it\nmakes of its own result: the `deps` commands have no `verified` block, so treat the\nquirks below as unchecked.\n\nOutput:\n\n```json\n{\n "ecosystems": ["npm", "nuget", "maven"],\n "manifests": [{ "file": "package.json", "ecosystem": "npm", "lockFile": "package-lock.json" }],\n "packages": [{ "name": "lodash", "version": "4.17.21", "ecosystem": "npm", "source": "package-lock.json", "type": "direct", "scope": "production" }],\n "summary": { "totalPackages": 1, "byEcosystem": { "npm": 1 }, "byType": { "direct": 1, "transitive": 0 }, "byScope": { "production": 1, "dev": 0 } }\n}\n```\n\nPaths are relative to the workspace, with forward slashes. Maven names are\n`group:artifact`. When the repository\'s root is above the workspace, only the\nworkspace is scanned: run it from the root, or pass `--workspace <root>`, to scan\neverything.\n\nKnown quirks, which stay until they\'re checked against real repositories:\n\n- In an npm v7+ lockfile, `direct` means hoisted to the top `node_modules`, so most\n transitive packages count as direct. Workspace folders show up as packages.\n- Yarn 1 headers with several ranges give a garbled name. Yarn 2+ lockfiles give no\n packages.\n- pnpm peer suffixes stay in the version, and pnpm 9\'s scoped packages are missed.\n- `CentralTransitive` NuGet packages count as direct.\n- `gradle.lockfile` test dependencies are always included.\n- Any `word \'a:b:c\'` string in `build.gradle` reads as a dependency.\n- `pom.xml` plugin dependencies count as the project\'s.\n\nThe output is the inventory the vulnerability and licence commands read from stdin\nor `--from <file>`: `toil osv vulns`, `toil ossindex vulns`, `toil sonatypeiq\nevaluate`, and `toil artifactory package outdated` / `license-check`. Over MCP, save it to a\nfile in the workspace and pass that file\'s path as `from`.\n\n### `toil util deps diff`\n\nHow the inventory changed between two git refs. This command runs the git on PATH:\n`git ls-tree` for each ref\'s files and `git show` for each one it reads. Without git\nit fails with `GIT_NOT_FOUND`.\n\n```bash\ntoil util deps diff --from main\ntoil util deps diff --from v1.0.0 --to main --ecosystem npm --include-dev\n```\n\n| Flag | Meaning |\n|------|---------|\n| `--from <ref>` | The base ref: a commit, tag or branch. Required |\n| `--to <ref>` | The target ref (default: the working tree, scanned as `deps scan` does) |\n| `--ecosystem <ecosystem>` | `npm`, `nuget`, `maven` or `all` (default) |\n| `--include-dev` | Include dev and test dependencies |\n\nTransitive dependencies are always included. Output: `{ from, to, changes: [{ name,\necosystem, change, from, to, source }], summary: { added, removed, upgraded,\ndowngraded, unchanged } }`. `change` is `added`, `removed`, `upgraded` or\n`downgraded`. Unchanged packages are counted, not listed. `to` reads `working tree`\nwhen `--to` is left out.\n\nKnown quirks:\n\n- A ref git can\'t read (a typo, or one you haven\'t fetched) gives an empty\n inventory for that side, so a bad `--from` reports every package as `added`.\n Check the ref first.\n- Each package is keyed on ecosystem, name and source file, and one version per key\n survives. A package present at two versions can show a change that didn\'t happen.\n- Paths that git quotes (non-ASCII names) aren\'t read at a ref.\n- A ref that starts with `-`, or an empty `--from`, is refused with `INVALID_INPUT` before git runs. An empty `--to` means the working tree.\n\n### `toil util secrets scan`\n\nFinds credential-shaped strings before an agent or a person commits, pushes,\ncomments or posts them. It reads a file, a folder, stdin, text, or the\nrepository\'s staged or working-tree diff, and talks to nothing.\n\n```bash\ntoil util secrets scan --diff staged # before git commit\ntoil util secrets scan src/ # a folder, .gitignore respected\ntoil util secrets scan notes.md\ngh pr view 12 --json body -q .body | toil util secrets scan -\ntoil util secrets scan --text "$COMMENT"\n```\n\n| Argument / flag | Meaning |\n|-----------------|---------|\n| `[path]` | A file or folder inside the workspace. A folder is walked as `git ls-files --cached --others --exclude-standard` would list it. `-`, or nothing at all, reads stdin |\n| `--text <text>` | The content itself, instead of a file |\n| `--diff <kind>` | `staged` scans what the next commit holds (`git diff --staged`); `working` scans unstaged changes (`git diff`). Added lines only, in the workspace only. Runs the git on PATH |\n| `--allow-file <file>` | The allow file (default: `.toil/secrets-allow` at the workspace\'s top, when it exists) |\n\nPass one of a path, `--text` or `--diff`; two at once is `INVALID_INPUT`. Over\nMCP, pass `file`, `text` or `diff`.\n\nA folder that `.gitignore` excludes is walked as git lists it: only the files git\ntracks there. When that\'s none, the result has no findings and a\n`SECRETS_NOTHING_SCANNED` warning saying 0 files were scanned and why; name a file\nin the folder to scan that file.\n\n**The exit code is 1 when anything is found**, and 0 when nothing is, so a hook\nor a pipeline can gate on it. The envelope stays `ok: true` either way; `ok:\nfalse` (also exit 1) means the scan itself failed.\n\n**What it looks for:**\n\n- The rules the audit log redacts with, so toil has one definition of a\n secret: GitHub, GitLab, Slack (tokens and webhook URLs), AWS, SonarQube, `sk-`,\n Atlassian, Bitbucket Data Center, npm, Artifactory, Dynatrace, Figma and Azure\n DevOps tokens, Azure SAS signatures (`sig=`), JWTs, private keys, credentials\n in URLs, `Bearer` / `Basic` / `Token`\n values, `name=value` pairs whose name says secret (`password=`,\n `"apiToken":`, `--token=`), `curl -u user:pass`, and long random runs of\n letters and digits.\n- `high-entropy`: a run of 20 or more base64 or base64url characters, holding\n letters and digits, that those rules didn\'t catch and whose Shannon entropy\n is at least 4.2 bits per character.\n\nTwo things are set aside and counted instead of reported: Subresource Integrity\nchecksums (`sha512-\u2026` in lockfiles, counted in `summary.checksums`), and a named\nvalue that is a reference to a secret rather than one (`token: ${{ secrets.X }}`,\n`password=$DB_PASSWORD`, `<your-token>`, `xxx`, counted in\n`summary.placeholders`). Commits, digests and UUIDs aren\'t findings.\n\nOutput:\n\n```json\n{\n "source": { "kind": "staged", "path": null },\n "findings": [{ "file": "config/application.properties", "line": 4, "column": 28, "length": 14, "rule": "name-value", "confidence": "high", "entropy": 3.18, "preview": "\u2026", "fingerprint": "e594506f-49ad270a-55b41205-70d9b059" }],\n "allowed": [],\n "unreadable": [{ "file": "logo.png", "reason": "binary", "message": "logo.png is binary in the diff; its content wasn\'t scanned." }],\n "allowList": null,\n "summary": { "files": 1, "lines": 5, "findings": 1, "allowed": 0, "unreadable": 1, "checksums": 0, "placeholders": 0, "byRule": { "name-value": 1 } },\n "verified": { "passed": true, "checks": [] }\n}\n```\n\n- `file` is relative to the workspace, with forward slashes, or `null` for\n stdin and text. `line` and `column` start at 1; columns count UTF-16 code\n units. A private key spanning lines is one finding, with `endLine`.\n- `source.kind` is `file`, `folder`, `stdin`, `text`, `staged` or `working`.\n- `confidence` is `high` for a vendor\'s token format, `high` or `medium` for a\n value a name or scheme marks as secret (medium when it\'s short and plain),\n and graded by entropy for a random run (`low` below 3.5 bits per character).\n- **The full secret is never in the output**, nor in a warning, an error or the\n audit log, which keeps no copy of `text`. `preview` keeps at most 4\n characters at each end of a secret of 24 or more, 2 of one of 16 to 23, and\n none of a shorter one: `ghp_\u2026c9vB`, `\u2026`.\n- `fingerprint` identifies the value without revealing it: a salted scrypt,\n four groups of 8 hex digits. It\'s slow on purpose, so a short password can\'t\n be recovered from it by guessing at speed.\n\n**The allow file** lists known false positives, one fingerprint per line, copied\nfrom a finding. `#` starts a comment. It\'s matched by fingerprint only, never by\nthe raw value, so it\'s safe to check in. A finding it names goes in `allowed`\ninstead of `findings` and doesn\'t set the exit code. `allowList` says which file\nwas read, how many entries it had, how many lines weren\'t fingerprints, and how\nmany entries matched nothing. A line that isn\'t a fingerprint is ignored with a\n`SECRETS_ALLOW_INVALID` warning that gives its line number and never its text. A\nnamed `--allow-file` that doesn\'t exist is `INVALID_INPUT`.\n\n```text\n# .toil/secrets-allow\ne594506f-49ad270a-55b41205-70d9b059 # the test fixture\'s dummy password\n```\n\n**What it checks of its own result** (`verified`):\n\n- `finding.reread`: every finding is read again at its reported line, from the\n file on disk, from the index (`git show :<path>`) for a staged diff, or from\n what stdin or the text held. The same characters must be at the same column,\n with the same rule finding them. A mismatch warns `SECRETS_REREAD_MISMATCH`.\n- `preview.masked`: every preview is checked to hold none of the secret\'s\n middle. One that fails warns `SECRETS_PREVIEW_LEAK` and is replaced by `\u2026`.\n- `input.complete`: each file was read to its size on disk. For a diff this is\n `unchecked`, with an `UNVERIFIED` warning, since git\'s output has no size to\n compare with; the re-read checks each finding instead.\n\n**What it couldn\'t read is listed**, never skipped silently. `unreadable` holds\neach binary file, each file over 64 MiB, each one it couldn\'t open (a permission\nerror, say), each nested repository a folder scan didn\'t walk into, and each line\nover 4 MiB, of which only the start was scanned. Any of them adds a\n`SECRETS_UNREADABLE` warning. A single file named on the call that can\'t be read\nis an `INVALID_INPUT` error instead. `--diff working` also warns\n`SECRETS_UNTRACKED_NOT_SCANNED` with the number of untracked files, which no diff\nholds: scan the folder, or stage them, to include them.\n\n**A diff covers the workspace, not the whole repository.** When the workspace is\na folder inside the repository, changes outside it aren\'t scanned, and a\n`SECRETS_DIFF_PARTIAL` warning gives the number of changed files left out. To\ncheck a whole commit, run it with `--workspace` at the repository\'s top.\n\nKnown limits:\n\n- A diff and a file are scanned line by line, so a secret split across two lines\n (other than a private key) isn\'t found.\n- A private key spans lines only when its BEGIN line stands alone and an END\n line follows its body (base64, blank, `Proc-Type:` and `DEK-Info:` lines). It\'s\n then one finding, with `endLine`. When no END comes (another line, a gap\n between diff hunks, or the end of the file), the BEGIN line is reported on its\n own and the lines below it are scanned as usual.\n- A bare `key=` isn\'t treated as a secret\'s name, because in toil\'s inputs it\'s\n an issue, space or project key. A real key there is still caught by its shape\n or its entropy.\n\n### `toil util encode`\n\nEncodes or decodes base64, base64url, hex and URL percent-encoding, and hashes a\nfile with SHA-256, SHA-1 or MD5. Each result is checked before it\'s returned, and\n`data.verified` says how.\n\n```bash\ntoil util encode base64 --text \'you@example.com:abc12345\'\ntoil util encode base64 --decode mail-part.b64 --out logo.png\ntoil util encode url --text \'project = PAY AND assignee = "you@example.com"\'\ntoil util encode form --decode --text \'project+%3D+PAY+AND+assignee+%3D+%22you%40example.com%22\'\nprintf \'hello\' | toil util encode hex\ntoil util encode sha256 release.tgz\n```\n\n| Argument or flag | Meaning |\n|------------------|---------|\n| `<scheme>` | `base64`, `base64url`, `hex`, `url`, `form`, or a hash: `sha256`, `sha1`, `md5`. Required |\n| `[file]` | A file inside the workspace. `-`, or leaving out both the file and `--text`, reads stdin |\n| `--text <text>` | The content itself, instead of a file. It\'s encoded as UTF-8 |\n| `--decode` | Decode instead of encode. Not for a hash |\n| `--out <file>` | Write the result to this new file inside the workspace instead of returning it. Never replaces a file. Not for a hash |\n\nThe schemes:\n\n- **`base64`** is written padded. Decoding accepts it with or without padding, and\n ignores spaces and line breaks, so MIME-wrapped base64 reads as it is.\n- **`base64url`** (`-` and `_`) is written without padding, as JWTs use it, and\n read with or without.\n- **`hex`** is written in lower case and read in either. Spaces and line breaks are\n ignored; a `0x` prefix or `:` separators are not.\n- **`url`** is a URL component, written as JavaScript\'s `encodeURIComponent` writes\n it: letters, digits and `-_.!~*\'()` stay, every other byte becomes `%XX`.\n- **`form`** is one name or value of an `application/x-www-form-urlencoded` body:\n letters, digits and `*-._` stay, a space becomes `+`, and every other byte becomes\n `%XX`. Decode a body one field at a time. A whole body decodes, but its `=` and\n `&` come back the same as an encoded `%3D` and `%26`, so `roundtrip.encode`\n fails, as it should.\n\nOutput:\n\n- **Encode:** `{ operation: "encode", scheme, inputBytes, outputBytes, output, verified }`.\n- **Decode:** `{ operation: "decode", scheme, inputBytes, outputBytes, utf8, output, verified }`.\n `utf8` says whether the decoded bytes are valid UTF-8.\n- **Hash:** `{ operation: "hash", scheme, inputBytes, hex, base64, verified }`, the\n digest both ways.\n- With `--out`, `file` (the absolute path written) replaces `output`.\n\nThe input is bytes: a file or stdin is encoded or hashed exactly as it is, so\n`echo hello | toil util encode base64` includes the newline `echo` adds. Use\n`printf` or `--text` to leave it out. When decoding, one trailing line ending is\ndropped.\n\n**Decoded bytes that aren\'t valid UTF-8 are refused** with `INVALID_INPUT` unless\n`--out` names a file to write them to. JSON can only carry them as text, and any\ntext would be different bytes. Valid UTF-8 comes back as the text it is.\n\nWhat `data.verified` checks:\n\n| Check | What it means |\n|-------|---------------|\n| `roundtrip.decode` | An encode was decoded back, and gave exactly the input |\n| `roundtrip.encode` | A decode was encoded again, and gave the input, allowing for whitespace, padding, the case of hex and `%XX`, and `%20` for `+` in a form |\n| `input.complete` | The bytes read equal the file\'s size on disk, so a read that stopped short can\'t pass. Unchecked for stdin, which has no size |\n| `output.file` | The file written was read back, and holds exactly the bytes written |\n\nA failed check sets `verified.passed` to `false` and adds a warning:\n`ENCODE_ROUNDTRIP_MISMATCH`, `INPUT_INCOMPLETE` or `ENCODE_OUTPUT_MISMATCH`. Input\nthat decodes but fails `roundtrip.encode` isn\'t how the scheme writes those bytes.\nFor example, base64 `QR==` decodes to `A`, but base64 writes `A` as `QQ==`, and a URL\nwith a space left in it isn\'t encoded. Check that it wasn\'t changed on the way.\n\nErrors:\n\n- Text that isn\'t the scheme is `INVALID_INPUT`, naming the offset of the first\n character that\'s wrong but never the character, in case the text is a credential.\n A base64 character that only base64url uses (or the other way round) says to try\n the other scheme.\n- A file to decode that looks binary (a NUL byte), `--decode` or `--out` with a hash,\n and a scheme toil doesn\'t have are `INVALID_INPUT`.\n- Encoding or decoding reads at most 64 MiB. A hash of a file streams, with no\n limit; stdin is held in memory, so it keeps the 64 MiB limit.\n\nMD5 and SHA-1 are here to match checksums that other tools publish, not to protect\nanything. The audit log keeps only a hash of `--text`.\n\n### `toil util cert`\n\nDecodes X.509 certificates, one or a chain bundle, in PEM or DER, so you can\nexplain a TLS failure from the files. It never connects to the host the certificate\nis for: pass the file the server is configured with, or the chain a client saved.\n\n```bash\ntoil util cert chain.pem\ntoil util cert chain.pem --host api.imagile.dev\ntoil util cert server.der\ncat chain.pem | toil util cert -\n```\n\n| Argument or flag | Meaning |\n|------------------|---------|\n| `[file]` | A file in the workspace, PEM or DER. `-`, or leaving it out, reads stdin |\n| `--text <text>` | The PEM itself, instead of a file. Over MCP, `text` is read as UTF-8, so a DER certificate goes as `file` |\n| `--host <host>` | A host name or IP address: do the first certificate\'s SANs cover it? |\n\nOutput: `{ format, certificates, skipped, chain, host, verified }`. Each\ncertificate is `{ position, line, offset, subject, issuer, sans, serial, validity:\n{ notBefore, notAfter, daysLeft, status }, key: { type, bits, curve },\nsignatureAlgorithm: { name, oid }, selfSigned, basicConstraints: { ca, pathLength },\nkeyUsage, extendedKeyUsage, fingerprints: { sha1, sha256 } }`. `position` counts\nevery block in a PEM bundle (or element in a DER one) from 1, `line` is where a PEM\nblock starts and `offset` where a DER certificate does. `status` is `valid`,\n`expired` or `not-yet-valid`, and `daysLeft` is negative once expired.\n`basicConstraints`, `keyUsage` and `extendedKeyUsage` are null when the certificate\ndoesn\'t have that extension.\n\nWhat it checks, in `data.verified` (a failure also warns under its code):\n\n| Check | Means | Fails with |\n|-------|-------|------------|\n| `bundle.readable` | Every block meant to be a certificate decodes | `CERT_UNREADABLE` |\n| `decode.matchesNode` | toil\'s DER reader and `node:crypto` agree on the serial and CA flag, and nothing follows the certificate in its block | `CERT_DECODE_MISMATCH` |\n| `validity.notExpired`, `validity.started` | Each certificate is inside its validity window now | `CERT_EXPIRED`, `CERT_NOT_YET_VALID` |\n| `chain.order` | Each certificate\'s issuer is the next one\'s subject | `CERT_CHAIN_ORDER` |\n| `chain.signature` | Where the names match, each signature verifies with the next certificate\'s key, and a self-issued last certificate with its own | `CERT_SIGNATURE_MISMATCH` |\n| `chain.root` | Unchecked (`UNVERIFIED`) when the last certificate isn\'t self-signed, so its issuer doesn\'t follow it: the chain is checked only as far as the bundle goes | |\n| `host.covered` | With `--host`, a DNS or IP SAN of the first certificate covers it | `CERT_HOST_MISMATCH` |\n| `input.complete` | The whole file was read (unchecked for stdin) | `INPUT_INCOMPLETE` |\n\n- The chain is checked in the order given, leaf first. When it\'s out of order but\n is one chain in another order, `chain.suggestedOrder` lists the positions in the\n right order and `CERT_CHAIN_REORDER` says so.\n- `chain.inOrder` is true when every link\'s names match and every signature\n checked verifies. `chain.root` is `included` when the last certificate is\n self-signed. Nothing is checked against a trust store: a chain that verifies to\n a root in the bundle isn\'t thereby trusted.\n- `--host` follows what browsers do: SANs only, never the subject CN, and a\n wildcard covers exactly one label (`*.imagile.dev` covers `api.imagile.dev`, not\n `imagile.dev` or `a.api.imagile.dev`). `host.explanation` says why it\'s covered\n or not.\n- A PEM block that isn\'t a certificate is skipped, listed in `skipped` and named in\n a `CERT_BLOCK_SKIPPED` warning. A private key is never read, and\n `CERT_PRIVATE_KEY_IN_INPUT` says one was there. `CERTIFICATE` and\n `X509 CERTIFICATE` blocks are read; `TRUSTED CERTIFICATE`, PKCS#7 (`.p7b`) and\n PKCS#12 (`.pfx`) are not.\n- In DER input a damaged certificate ends the reading, since nothing says where the\n next one starts; it\'s reported at its byte offset.\n- Input with no certificate that can be read fails with `INVALID_INPUT`, naming\n each block and why.\n\n### `toil util semver`\n\nVersions and ranges in the grammar of the ecosystem they come from. Pick it with\n`--ecosystem`: `npm` (the default), `nuget` or `maven`.\n\n- **npm:** SemVer 2.0.0 versions (`1.2.3`, `1.2.3-rc.1+build.5`; a leading `v` is\n allowed) and npm\'s ranges, as `package.json` takes them: `^1.2.3`, `~1.2`, `1.x`, `>=1.0.0 <2.0.0`,\n `1.0.0 - 2.0.0`, joined with `||`. A prerelease satisfies a range only when the\n range names a prerelease of the same `major.minor.patch`, unless you pass\n `--include-prerelease`. There\'s no loose mode that turns text that isn\'t a\n version into one.\n- **nuget:** one to four numbers (`1`, `1.0` and `1.0.0.0` are one version), then\n an optional `-prerelease` and `+metadata`. Labels compare case-insensitively.\n Ranges are interval notation: `1.0` (at least 1.0), `[1.0]`, `[1.0,2.0)`,\n `(,2.0]`. A prerelease inside the bounds satisfies the range. Floating versions\n (`1.*`, `1.0.0-*`) are refused, because what one picks depends on the feed.\n- **maven:** Maven\'s own ordering: `alpha < beta < milestone < rc < snapshot <\n release < sp`, `1`, `1.0` and `1.0.0.Final` are one version, and `1a1` is\n `1-alpha-1`. A version is letters, digits, `.`, `-`, `_` and `+` with at least\n one digit, so an unresolved `${property}` is reported, not ordered. Ranges are\n `[1.0,2.0)`, `[1.0]` and `(,1.0],[1.2,)`. A bare version is a soft requirement\n that any version satisfies, and says so in a `MAVEN_SOFT_REQUIREMENT` warning.\n\nA version or range that doesn\'t parse in the chosen grammar is `INVALID_INPUT`,\nwith the reason and an example of what fits. Build metadata never affects order.\n\n```bash\ntoil util semver compare 1.0.0-rc.10 1.0.0-rc.9\ntoil util semver satisfies 1.3.0-rc.1 \'^1.2.0\' --include-prerelease\ntoil util semver satisfies 5.3.39 \'[5.0,6.0)\' --ecosystem maven\ntoil util semver sort versions.txt --range \'^5.0.0\'\ntoil util semver bump 1.2.3 prerelease --preid rc\n```\n\n| Command | Arguments and flags | Output |\n|---------|---------------------|--------|\n| `compare <a> <b>` | `--ecosystem <ecosystem>` | `{ ecosystem, a, b, order, higher, difference, normalized: { a, b }, verified }`. `order` is -1, 0 or 1 for a against b, `higher` is `a`, `b` or null, and `difference` is the most significant part they differ in: `major`, `minor`, `patch`, `revision` (NuGet\'s fourth part, or Maven\'s), `prerelease`, `qualifier` (Maven) or null |\n| `satisfies <version> <range>` | `--ecosystem <ecosystem>`, `--include-prerelease` | `{ ecosystem, version, range, normalizedRange, satisfies, verified }` |\n| `sort [file]` | `--text <text>`, `--ecosystem <ecosystem>`, `--range <range>`, `--include-prerelease` | `{ ecosystem, count, sorted, invalid, verified }`, lowest first, plus `{ range, normalizedRange, satisfying, highest }` with `--range` |\n| `bump <version> <release>` | `--ecosystem <ecosystem>`, `--preid <id>` | `{ ecosystem, version, release, preid, result, verified }` |\n\n- **`sort`** reads a file in the workspace, stdin (`-`, or no file), or `--text`.\n Versions go one per line or separated by spaces. An entry that doesn\'t parse is\n left out of the sort and listed in `invalid` with its line and the reason, with a\n `SEMVER_INVALID_VERSION` warning.\n- **`bump`** takes `major`, `minor` or `patch` in every ecosystem. npm also takes\n `premajor`, `preminor`, `prepatch`, `prerelease` and `release`, the bumps npm\n publishes with, and `--preid` names the prerelease (`1.2.3` `prerelease --preid rc` is\n `1.2.4-rc.0`). A NuGet result has three parts, with the revision and labels\n dropped. Maven bumps the leading numbers and drops the qualifier\n (`1.2.3-SNAPSHOT` `minor` is `1.3.0`).\n\n**What it checks** (`verified`, with failures as warnings):\n\n- `sort.transitive`: every pair in the sorted list is in order, so a comparison\n where a < b and b < c but not a < c can\'t hide. Up to 2,000 versions; past that,\n each against its neighbour, reported as `APPROXIMATED`.\n- `sort.antisymmetric`, `sort.complete`: each neighbouring pair compares the same\n both ways round, and every entry is either sorted or listed as invalid.\n- `range.boundaries`, `range.answers`: each answer agrees with the range\'s\n intervals, worked out by comparison alone, at the range\'s boundary versions and\n at every version asked about. A range with no bounds (`*`) has none to test, and\n says so with `UNVERIFIED`.\n- `compare.antisymmetric`, `diff.consistent`, `bump.increases`,\n `version.normalized`: b against a is the reverse of a against b, a difference is\n named exactly when the versions differ, a bump goes up, and a normalised version\n reads back as the same version.\n- `input.complete`: the whole file was read. stdin has no size to compare with, so\n it\'s `UNVERIFIED`.\n\n`diff` names the most significant part that changed, the same rule in every\necosystem; it never answers `premajor` or the like.\n\n### `toil util report`\n\nOne JSON summary of a report that CI or a scanner wrote: JUnit XML, TRX, SARIF\n2.1.0, lcov or Cobertura. It reads the file and nothing else, and checks the report\nagainst its own declared totals.\n\n```bash\ntoil util report target/surefire-reports/TEST-dev.imagile.OrderTest.xml\ntoil util report TestResults/build.trx\ntoil util report coverage/lcov.info --lowest 5\ntoil util report results.sarif\ncat coverage.xml | toil util report --format cobertura\n```\n\n| Argument / flag | Meaning |\n|-----------------|---------|\n| `[file]` | The report, inside the workspace. `-`, or no file and no `--text`, reads stdin |\n| `--text <text>` | The report itself, instead of a file |\n| `--format <format>` | `junit`, `trx`, `sarif`, `lcov` or `cobertura`. Left out, it\'s detected from the content: the root element for XML (`<testsuites>` or `<testsuite>`, `<TestRun>`, `<coverage>`), `"runs"` for SARIF, a first `TN:` or `SF:` line for lcov |\n| `--lowest <n>` | How many of the lowest-covered files to list (default 10, up to 1000) |\n\nOver MCP the tool is `util_report`, with `file` or `text`, `format` and `lowest`.\n\nOutput: `{ format, formatFrom, tests, findings, coverage, skipped, verified }`.\n`formatFrom` is `content` or `flag`. One of `tests`, `findings` and `coverage` is\nfilled in, by format, and the other two are `null`.\n\n- **`tests`** (JUnit, TRX): `{ suites, totals: { tests, passed, failures, errors,\n skipped, flaky, other }, failures: [{ suite, name, className, kind, type,\n message, file, line, location, stack, stackLines }] }`. The totals are recounted\n from the cases, never copied from the report. `kind` is `failure` or `error`.\n `stack` is the first 15 lines, and `stackLines` how many there were. `location` is\n `report` when the report states `file` or `line`, and `stack` when they were read\n from the first stack frame naming the test\'s class or method (an `APPROXIMATED`\n warning says how many). It\'s `null` when neither has one.\n- **`findings`** (SARIF): `{ runs: [{ tool, version, results }], total, byLevel,\n results: [{ tool, rule, level, kind, file, line, message, suppressed }] }`. `level`\n follows the spec: the result\'s own, else its rule\'s default, else `warning` for a\n failing result and `none` for any other. `file` is the first location\'s URI as\n written, and `line` its `startLine`.\n- **`coverage`** (lcov, Cobertura): `{ sources, totals: { lines, branches }, files:\n [{ file, lines, branches }], lowest }`. Each figure is `{ covered, total, percent }`,\n with `percent` rounded to two places (`null` when there\'s nothing to cover).\n `branches` is `null` where the report has no branch data. `lowest` lists the\n `--lowest` files with the lowest line coverage, leaving out files with no lines.\n- **`skipped`**: `{ count, elements: [{ element, count, reason }] }`, every element\n (or lcov record) the reader met and didn\'t read, also warned as\n `REPORT_ELEMENTS_SKIPPED`. Known parts that hold nothing it summarises\n (`system-out`, `properties`, TRX\'s settings and lists, Cobertura\'s per-method copies\n of the lines) aren\'t counted.\n\nWhat `verified` checks:\n\n| Format | Check | Warning when it fails |\n|--------|-------|-----------------------|\n| JUnit | Each suite\'s (and `<testsuites>`\') declared `tests`, `failures`, `errors` and `skipped`, recounted from its cases, nested suites included | `REPORT_TOTALS_MISMATCH`, naming both numbers |\n| TRX | `<Counters>`\' `total` and each outcome counter, recounted from the results\' `outcome` | `REPORT_TOTALS_MISMATCH` |\n| Cobertura | Every stated `line-rate` and `branch-rate` (class, package and root), to within one unit of its last written decimal, and the root\'s `lines-covered`, `lines-valid`, `branches-covered` and `branches-valid` | `REPORT_COVERAGE_MISMATCH` |\n| lcov | Each record\'s `LF`, `LH`, `BRF`, `BRH`, `FNF` and `FNH`, recounted from its `DA`, `BRDA`, `FN` and `FNDA` lines | `REPORT_COVERAGE_MISMATCH` |\n| SARIF | Each `ruleIndex` points at the rule its `ruleId` names | `REPORT_SARIF_INCONSISTENT` |\n| All | The whole input was read (`input.complete`) | `INPUT_INCOMPLETE`, or `INPUT_TRUNCATED` at the cap |\n\nWhat it can\'t check is reported as `UNVERIFIED`, never as passed: a JUnit report\nthat declares no totals, SARIF (which declares none), a TRX counter left at `0` over\nresults with that outcome (VSTest leaves `notExecuted` at 0, for one), and the size\nof stdin. TRX\'s `executed` isn\'t compared, because writers disagree on what it\ncounts.\n\nFormats it reads:\n\n- **JUnit:** Maven Surefire\'s, the Jenkins shape (nested `<testsuite>`s, `status`,\n `assertions`, `disabled`) and the Azure DevOps shape (the VSTest JUnit logger\'s).\n Surefire\'s `flakyFailure` and `flakyError` mean a rerun passed: the case counts as\n passed and in `flaky`. A case with `<error>` is an error, else one with\n `<failure>` is a failure, else one with `<skipped>` is skipped.\n- **TRX:** `dotnet test --logger trx` and Visual Studio\'s. Top-level results are\n counted, as the counters count them, and a data-driven test\'s inner rows aren\'t.\n `failures` is `Failed`; `errors` is `Error`, `Timeout` and `Aborted`; `skipped` is\n `NotExecuted` and `NotRunnable`; any other outcome is `other`. `suites` is the\n number of test classes, and a failure\'s `suite` is its class.\n- **SARIF 2.1.0:** any tool\'s. A rule reference with a `toolComponent` index is\n looked up in that entry of `tool.extensions` (CodeQL query packs); one that names\n its component only by `guid` can\'t be found, so `sarif.ruleIndex` is `UNVERIFIED`\n and the level falls back to `warning`. A file with another `version` is read as\n 2.1.0, with an `APPROXIMATED` warning. A run whose invocation says it failed warns\n `REPORT_TOOL_FAILED`.\n- **lcov:** `SF` to `end_of_record` records, including lcov 2\'s `FNL` and `FNA`.\n `FNH` is recounted as distinct functions hit: `FNA` by index, so a function\'s\n aliases count once, and `FNDA` by name. A file in several records is merged, and a\n line is covered when any record hit it.\n- **Cobertura:** coverlet\'s, coverage.py\'s and others\'. Classes in the same file are\n added together, and branch counts come from `condition-coverage="50% (1/2)"`.\n\nLimits: XML and lcov stream, so memory stays flat for a report of any size, apart\nfrom the failures it lists, up to the 64 MiB input cap. At the cap the read stops,\n`INPUT_TRUNCATED` says so, `input.complete` fails, and what came before the cut is\nsummarised; a suite the cut left open isn\'t compared. SARIF is JSON and is read\nwhole, so a SARIF file over the cap is `INVALID_INPUT`. Malformed XML or JSON is\n`INVALID_INPUT` with the line and column. So is a document whose format can\'t be\ndetected, or whose root doesn\'t match `--format`, with a fix naming `--format`.\n\n### `toil util log`\n\nTriages a large log (a CI console, a Maven, npm or dotnet build, a test run) into\nwhat\'s worth reading: its error and warning lines grouped by signature, each with the\nstack trace that follows it. It reads the file only, streams it, and holds memory\nconstant however large the log is.\n\n```bash\ntoil util log build.log\ntoil util log console.log --level error --context 3\ntoil util log console.log --since 2026-10-14T09:12:00Z --grep \'Failed to execute\'\nsome-build 2>&1 | toil util log -\n```\n\n| Argument or flag | Meaning |\n|------------------|---------|\n| `[file]` | The log, inside the workspace. `-`, or no file and no `--text`, reads stdin |\n| `--text <text>` | The log itself, instead of a file |\n| `--since <timestamp>` | Only lines dated at or after this ISO 8601 time (`2026-10-14`, `2026-10-14T09:12:00Z`, `"2026-10-14 09:12:00"`). A line with no date takes the date of the last dated line before it. Without a zone, a time is read as UTC |\n| `--level <level>` | `warning` (default) reports errors and warnings; `error` reports errors only |\n| `--grep <regex>` | Only error and warning lines matching this JavaScript regular expression (case-sensitive, no slashes or flags). An error also matches when the exception line heading its trace does (`--grep IllegalStateException`). Frames aren\'t searched; `LOG_GREP_STACK_ONLY` says when only they matched |\n| `--max-groups <n>` | The most groups to return, default 50, up to 1000 |\n| `--context <n>` | Lines to show before and after each group\'s sample, default 0, up to 20 |\n\nOver MCP the tool is `util_log`, with `file` (a path in the workspace) or `text`, and\nthe same fields: `since`, `level`, `grep`, `maxGroups`, `context`.\n\nHow it reads a log:\n\n- **Timestamps:** a leading timestamp, bracketed (Jenkins\' timestamper) or bare (CI\n runners, log4j, Serilog), is set aside before anything else, so it never splits a\n group.\n- **Levels:** the first level word decides (`ERROR`, `FATAL`, `SEVERE`, `WARN`,\n `WARNING`, `INFO`, `DEBUG` \u2026, and npm\'s `npm error` / `npm warn`). A line tagged\n `INFO`, or with no tag, is still an error by its shape: `BUILD FAILURE`, `FAILED`,\n `error CS0246:`, `error TS2322:`, `TypeError: \u2026`, `Unhandled exception.`, an eslint\n or vstest failure line. A tag with nothing after it (`[ERROR] `) is not a group.\n- **Signatures:** dates and times, UUIDs, hex and every number are replaced, and\n spaces collapsed. Codes such as `CS0246` and `TS2322` keep their digits, and paths\n and quoted names stay, so two different errors stay apart.\n- **Stack traces:** Java (`at \u2026(File.java:12)`, `Caused by:`, `... 14 more`), .NET\n (`at \u2026 in file:line 9`, `--->`, `--- End of inner exception stack trace ---`), Node\n (`at fn (file:12:3)`) and Python (`Traceback (most recent call last):`, printed\n before its exception) are joined to the error they belong to, with the exception\n line that heads one. An exception line joins an error, never a warning: after a\n warning it\'s an error of its own. A trace is reported for each group\'s first occurrence, up to\n 50 lines.\n\nOutput:\n\n```json\n{\n "lines": { "total": 76, "error": 20, "warning": 5, "other": 35, "stack": 12, "unclassified": 4 },\n "matched": 25, "filtered": 0, "groupsTotal": 18, "truncated": false, "ungrouped": 0, "unjoinedFrames": 0,\n "groups": [{\n "level": "error",\n "signature": "[ERROR] /build/ledger/Reconciler.java:[<n>] cannot find symbol",\n "count": 4, "firstLine": 27, "lastLine": 52,\n "sample": "[ERROR] /build/ledger/Reconciler.java:[54,38] cannot find symbol",\n "trace": { "kind": "java", "firstLine": 57, "lastLine": 68, "frames": 12, "lines": ["\u2026"] },\n "context": { "before": [{ "line": 26, "text": "\u2026" }], "after": [{ "line": 28, "text": "\u2026" }] }\n }],\n "verified": { "passed": true, "checks": [{ "check": "lines.reread", "status": "passed", "checked": 36, "failed": 0 }] }\n}\n```\n\nGroups are errors first, then warnings, each in order of first appearance. `lines`\nclasses every line once: `other` is a level below warning, `stack` a trace line, and\n`unclassified` a line with no level at all. `filtered` counts the error and warning\nlines `--since`, `--level` or `--grep` left out.\n\nIt checks its own answer, in `data.verified`:\n\n- **`lines.reread`:** every group\'s first line is read again from the file and must\n be its sample, and its last line must still have its signature. `trace.reread`\n does the same for every trace line shown. A mismatch is `LOG_LINE_MISMATCH`, which\n usually means the file changed while it was read.\n- **`groups.sum`, `lines.sum`, `filter.sum`:** the group counts add up to the matched\n lines, the line classes to the lines read, and matched plus filtered to the error\n and warning lines. A mismatch is `LOG_COUNT_MISMATCH`.\n- **`input.complete`:** the bytes read equal the file\'s size. It\'s `unchecked` for\n stdin and text.\n\nWhat it reports in `meta.warnings` rather than leave out: `LOG_UNCLASSIFIED` (lines\nwith no level, in no group), `LOG_GROUPS_TRUNCATED` (more groups than\n`--max-groups`), `LOG_UNGROUPED` (matched lines whose signature came after the first\n2,000 distinct ones, counted but not grouped, which is what keeps memory constant),\n`LOG_TRACE_UNJOINED` (trace lines with no error before them), `LOG_GREP_STACK_ONLY`\n(`--grep` matched only stack trace lines), `LOG_SINCE_UNDATED`\n(lines `--since` couldn\'t date, kept), and `APPROXIMATED` for a line longer than\n4,096 characters (grouped by its start) or a `--since` compared with times that had\nno zone.\n\nA file streams with no size limit. stdin and `--text` are held in memory, up to\n64 MiB, so pass a file for anything bigger.\n\n`--grep` runs in a worker thread, a batch of up to 4,096 lines at a time, each batch\nwith 2 seconds and 256 MB. A pattern that backtracks without end on some line, such as\n`(a+)+b`, fails the command with `TIMEOUT` naming the lines, rather than holding it.\n\n### `toil util size`\n\nHow big a file or folder is before you read it, so an agent can budget its\ncontext: bytes, lines and an estimated token count, and for one file an outline\nwith line ranges, so you can read just the part you need.\n\n```bash\ntoil util size src/areas/util/size.ts\ntoil util size src --depth 2 --top 5\ngit show HEAD:README.md | toil util size - --language markdown\n```\n\n| Argument / flag | Meaning |\n|-----------------|---------|\n| `[file]` | A file or folder inside the workspace. `-` (or nothing) reads stdin |\n| `--text <text>` | The content itself, instead of a file |\n| `--language <language>` | Outline it as this language: `typescript`, `javascript`, `python`, `csharp`, `java`, `go`, `markdown`, `json` or `yaml`. Needed for stdin and `--text`; for a file it overrides the extension |\n| `--top <n>` | For a folder: how many of the largest files to list (default 10) |\n| `--depth <n>` | For a folder: how many levels of subfolders the tree shows (default 3). Deeper folders still count in their parent\'s totals, and `foldersHidden` says how many were left out |\n\n**Tokens are an estimate**: `ceil(characters / 4)` per file, counting Unicode code\npoints. No model\'s tokenizer is bundled, and real counts vary by model and\ncontent. Every result says so in `tokenMethod` and with an `APPROXIMATED` warning.\n\n**For a file**: `{ kind: "file", path, language, bytes, lines, tokens, tokenMethod,\noutline, notOutlined, verified }`. `outline` is `{ precision, method, symbols }`,\neach symbol `{ name, kind, startLine, endLine, container }` (headings add `level`):\n\n- **Code** (`precision: "syntactic"`): TypeScript and JavaScript (`.ts`, `.tsx`,\n `.mts`, `.cts`, `.js`, `.jsx`, `.mjs`, `.cjs`), Python, C#, Java and Go. Functions,\n classes, interfaces, types, enums, namespaces, methods, constructors, C#\n properties and exported names. It\'s a pure-JavaScript scan that skips comments\n and strings and matches braces (indentation for Python), not a compiler, so\n `method` says what each language covers. Function bodies aren\'t searched, and\n fields aren\'t listed. `container` is the enclosing class or namespace.\n- **Markdown**: ATX and setext headings, outside code fences and front matter.\n- **JSON and YAML** (`precision: "parsed"`): the top-level keys, found by scanning\n and held against what the parser returns.\n\nWhen there\'s no outline, `outline` is null and `notOutlined` says why: `binary` (a\nNUL byte in the first 8,000 bytes; lines and tokens are null too),\n`unsupported-language`, `parse-error` (with the line, never the text, or that it\nnests too deep to outline; also a `SIZE_PARSE_ERROR` warning) or `too-large` (over\n8 MiB; it\'s still counted).\n\nThe outline is made in a worker thread with 10 seconds and 512 MB; a file at the\n8 MiB limit takes under 2 seconds. Past either, the command fails with `TIMEOUT` or\n`INVALID_INPUT` naming the file and the limit.\n\n**For a folder**: `{ kind: "folder", path, tokenMethod, totals, tree, largest,\nskipped, verified }`. It lists files the way `deps scan` does, skipping what\n`.gitignore` ignores. `totals` and every `tree` node hold `files`, `bytes`, `lines`,\n`tokens` and `binaryFiles`; binary files count in files and bytes only. Folders are\nsorted largest first. `largest` names the biggest files with their language.\n`skipped` lists what wasn\'t counted, with the reason: `unreadable` (with a\n`SIZE_FILES_SKIPPED` warning), `not-a-file` or `nested-repository`.\n\n**What it checks**, in `data.verified`:\n\n- `outline.start`: each symbol\'s start line, re-read from the input, names it.\n- `outline.range` and `outline.nesting`: each range is inside the file and in\n order, and a member sits inside its container.\n- `outline.keys`: JSON and YAML keys match the parser\'s.\n- `counts.reread`: the outline\'s full read gives the same bytes and lines.\n- `totals.sum` and `tree.sum`: the totals equal the files added up, and each\n folder equals its own files plus its subfolders.\n- `input.complete`: every file was read to its size on disk.\n\nA failed check sets `verified.passed` to false and warns `SIZE_OUTLINE_MISMATCH`,\n`SIZE_TOTALS_MISMATCH` or `SIZE_COUNTS_MISMATCH`.\n\n### Time: `toil util time`\n\nDate and time arithmetic on the time zone data Node ships (IANA, through `Intl`);\ntoil bundles no zone database of its own, and nothing reads the network. Each\ncommand checks its own answer a second way and reports the checks in\n`data.verified` (`{ passed, checks }`), with anything it couldn\'t check or had to\napproximate in `meta.warnings` as `UNVERIFIED` or `APPROXIMATED`.\n\nTimes are ISO 8601: a date (`2026-03-08`), a wall clock (`2026-03-08T02:30`), or an\ninstant with `Z` or an offset (`2026-03-08T07:30:00Z`, `2026-03-08T02:30:00-05:00`).\n`@1760000000` is epoch seconds, and `now` is the current time, read once per call.\nFields out of range (`2026-02-29`, `24:00`, a leap second) are `INVALID_INPUT`,\nnever rolled over. Digits below a millisecond are dropped with an `APPROXIMATED`\nwarning. Zones are IANA names (`America/New_York`); an unknown one is\n`INVALID_INPUT`.\n\n**DST.** A wall clock a zone skipped (spring forward) or showed twice (fall back) is\nalways reported, in `data` as a `dst` object and in `meta.warnings` as\n`TIME_DST_GAP` or `TIME_DST_OVERLAP`. A gap is read as the time the clocks showed\nafter the jump (02:30 becomes 03:30) and an overlap as the earlier of the two. Give\nthe time an offset to choose otherwise.\n\n#### `toil util time convert`\n\n```bash\ntoil util time convert 2026-03-08T02:30 --zone America/New_York --to UTC --to Europe/London\ntoil util time convert now --to Asia/Kolkata\n```\n\n| Argument or flag | Meaning |\n|------------------|---------|\n| `<time>` | The time to convert |\n| `--zone <zone>` | The zone of a time written without an offset. Required for one; refused for a time that has an offset |\n| `--to <zone>` | A zone to convert to (repeatable; default `UTC`) |\n\nOutput: `{ input, instant, epochMs, source: { kind, zone, offset, dst? }, results:\n[{ zone, local, offset, offsetSeconds, dst? }], verified }`. `local` is the time in\nthat zone with its offset. Checks: each result reads back as the same instant\n(`convert.roundtrip`), the zone shows that wall clock then (`convert.zone`), and a\nwall-clock input is what its zone shows at the instant found (`convert.source`). A\nfailure warns `TIME_ROUNDTRIP_MISMATCH`.\n\n#### `toil util time duration`\n\n```bash\ntoil util time duration P1DT2H30M\ntoil util time duration --seconds 93784.5\n```\n\n| Argument or flag | Meaning |\n|------------------|---------|\n| `<duration>` | An ISO 8601 duration to read: `PT1H30M`, `P1Y2M10DT2H`, `PT0.5S`, `-PT15M`. Only the last part may have a fraction |\n| `--seconds <seconds>` | Instead, a number of seconds to write as a duration |\n\nOutput: `{ input, iso, negative, parts: { years, months, weeks, days, hours,\nminutes, seconds }, totalSeconds, text, verified }`. `iso` is the canonical text.\nSeconds are written in hours, minutes and seconds only (`PT26H3M4.5S`), since a day\nisn\'t always 24 hours. Years and months have no fixed length, so `totalSeconds` is\n`null` with an `UNVERIFIED` warning; days and weeks count as 24 hours and 7 days,\nwith an `APPROXIMATED` warning. Check: the canonical text reads back as the same\nparts (`duration.roundtrip`, warning `DURATION_ROUNDTRIP_MISMATCH`).\n\n#### `toil util time business-days add` and `diff`\n\n```bash\ntoil util time business-days add 2026-12-23 3 --holidays holidays-2026.txt\ntoil util time business-days add 2026-12-28 -1\ntoil util time business-days diff 2026-12-24T15:00 2026-12-29T10:00 --zone America/Chicago --holiday 2026-12-25\n```\n\n| Argument or flag | Meaning |\n|------------------|---------|\n| `<start>` | The start time or date |\n| `<days>` | `add`: business days to add; negative subtracts |\n| `<end>` | `diff`: the end time or date |\n| `--zone <zone>` | The zone whose calendar days count, and the zone of a time without an offset (default `UTC`) |\n| `--holidays <file>` | A file in the workspace: one `YYYY-MM-DD` per line, optionally followed by a name; `#` lines are comments. Any other line is `INVALID_INPUT` naming it |\n| `--holiday <date>` | A holiday as `YYYY-MM-DD` (repeatable) |\n\nBusiness days are Monday to Friday, less the holidays given. No country\'s holidays\nare built in: list the dates the office is actually shut (the observed Friday, not\nthe Saturday it stands in for).\n\n`add` counts as a spreadsheet\'s `WORKDAY` does: the start never counts, each step\nlands on the next business day, and `0` returns the start unchanged. A time of day\nis kept, and a result in a DST gap or overlap is warned about. Output: `{ start,\ndays, zone, result, weekday, skipped: { weekendDays, holidays }, holidaysListed,\ndst?, verified }`. Checks: the business days between start and result, counted\nagain day by day, number `days` (`business.count`); the result is a business day\n(`business.landing`); and it\'s on the right side of the start\n(`business.direction`). A failure warns `BUSINESS_DAYS_MISMATCH`.\n\n`diff` measures the time between two times that falls on business days in the\nzone. A date means midnight. Output: `{ start, end, zone, negative, businessDays,\nhours, duration, totalBusinessSeconds, elapsedSeconds, holidays, verified }`:\n`businessDays` is whole 24-hour days of business time, `hours` what\'s left over,\nand `duration` the same, exactly (`PT43H`). DST days count as the 23 or 25 hours\nthey are. Checks: business time plus the rest adds up to the elapsed time\n(`business.partition`), and the days and hours make the business time\n(`business.total`), warning `BUSINESS_TIME_MISMATCH`.\n\n#### `toil util time cron`\n\n```bash\ntoil util time cron "*/15 9-17 * * 1-5" --zone Europe/London --count 10\ntoil util time cron "0 0 12 ? * MON#2" --dialect quartz\ntoil util time cron "H H(0-7) * * 1-5" --dialect jenkins --job platform/api-build\n```\n\n| Argument or flag | Meaning |\n|------------------|---------|\n| `<expression>` | The cron expression, quoted |\n| `--dialect <dialect>` | `standard`, `quartz` or `jenkins` (default: detected: 6 or 7 fields is `quartz`, an `H` is `jenkins`, otherwise `standard`) |\n| `--zone <zone>` | The zone the schedule runs in (default `UTC`) |\n| `--from <time>` | List runs after this time (default `now`) |\n| `--count <n>` | How many run times to list, 1 to 100 (default 5) |\n| `--job <name>` | The Jenkins job\'s full name (`folder/job`), which `H` is hashed from. Required when the expression uses `H` |\n\nThe dialects:\n\n- **standard**: five fields, minute hour day-of-month month day-of-week, as the classic\n crontab reads them. Names (`JAN`, `MON`), ranges, lists and steps (`*/15`,\n `1-30/5`, `5/15`); day-of-week 0 to 7, with 0 and 7 both Sunday. Macros `@yearly`,\n `@annually`, `@monthly`, `@weekly`, `@daily`, `@midnight` and `@hourly`; `@reboot`\n is refused, since it has no times. When neither day field starts with `*`, a day\n matching **either** runs. A detected standard expression with both day fields set\n warns `CRON_DIALECT_ASSUMED`, since Jenkins reads it differently.\n- **quartz**: six or seven fields, second first and an optional year (1970 to 2099)\n last. Day-of-week is 1 to 7 from Sunday. One of the day fields must be `?`.\n Day-of-month takes `L`, `L-3`, `15W` (the weekday nearest the 15th, inside the\n month) and `LW`; day-of-week takes `6L` (the last Friday) and `6#3` (the third\n Friday). A backwards range wraps (`FRI-MON`, `22-2`).\n- **jenkins**: five fields like standard, plus `H`, `H(0-7)` and `H/15`, placed as\n Jenkins places them from the job\'s full name. An unbounded `H` in day-of-month\n stays within 1 to 28. Both day fields must match. The macros use `H` (`@daily` is\n `H H * * *`, `@midnight` is `H H(0-2) * * *`), so pass `--dialect jenkins` for a\n Jenkins macro: a bare macro is detected as standard.\n\nOutput: `{ expression, dialect, dialectSource, zone, from, explanation, fields,\nruns: [{ instant, local, offset, dst? }], skipped, skippedTotal, verified }`. `fields` holds what\neach field expanded to, with day-of-week 0 for Sunday in every dialect.\n\nDST: a run time the zone skipped isn\'t listed as a run; it\'s in `skipped`, with a\n`CRON_DST_GAP` warning giving the total. `skipped` lists the first 100 and\n`skippedTotal` counts them all. The walk stops after 5,000 skipped run times (more\nthan one every-second gap hour), warning `CRON_SEARCH_STOPPED` with the last one\nreached, so a schedule that only lands in gaps (`* * 2 ? 3 1#2` in New York) answers\nat once; pass a later `--from` to look further. A run time that happened twice is listed once, at the first,\nwith a `dst` object and a `CRON_DST_OVERLAP` warning. Schedulers differ on both, so\ncheck yours. Fewer runs than `--count` in the next 100 years (or in Quartz\'s listed\nyears) warns `CRON_FEW_RUNS`; `0 0 30 2 *` never runs.\n\nChecks: each run, read back as the wall clock its zone shows then, matches every\nfield again (`cron.rematch`); the runs come after `--from` and in order\n(`cron.order`); `local` is the same instant (`cron.local`); and each skipped time\nreally is in a gap (`cron.gap`). A failure warns `CRON_RUN_MISMATCH`. The\nexplanation\'s wording isn\'t checked, and says so (`UNVERIFIED`): it\'s built from the\nsame fields the run times come from, and the run times are what\'s checked.\n\n### `toil util md`\n\nConverts a document between Markdown and the rich-text formats the Atlassian\nareas send: Jira wiki markup (Jira Data Center), Atlassian Document Format\n(Jira Cloud, Confluence Cloud) and Confluence storage format (Confluence Data\nCenter). One side is always Markdown. Every result is checked by converting it\nback, so you\'re told exactly what didn\'t survive.\n\n```bash\ntoil util md description.md --to wiki\ntoil util md page.md --to storage\ntoil util md description.md --to adf --select output\ntoil util md PROJ-142.wiki --from wiki\ntoil util md description.adf.json --from adf\n```\n\nADF input is the document itself, `{ "type": "doc", "version": 1, "content": [...] }`:\nan issue\'s `fields.description` or a comment\'s `body`, not the issue around it.\n\n| Argument / flag | Meaning |\n|-----------------|---------|\n| `[file]` | A file inside the workspace. `-`, or no file and no `--text`, reads stdin |\n| `--text <text>` | The document itself, instead of a file |\n| `--to <format>` | `wiki`, `adf` or `storage`, to convert Markdown into it |\n| `--from <format>` | `wiki`, `adf` or `storage`, to convert it into Markdown |\n\nOver MCP the tool is `util_md`, with `file` or `text` plus `from` or `to`.\n\nOutput:\n\n```json\n{\n "from": "md",\n "to": "wiki",\n "output": "h2. Steps\\n\\n# Open the login page\\n...",\n "lossless": false,\n "losses": [{ "construct": "task list", "at": "line 12", "detail": "Jira wiki markup has no task lists; each task is written as [ ] or [x] text" }],\n "roundTrip": { "blocks": 9, "differences": [] },\n "verified": { "passed": true, "checks": [{ "check": "roundTrip.blocks", "status": "passed", "checked": 9, "failed": 0 }] }\n}\n```\n\n- **`output`** is the converted document: an ADF document object for `adf`,\n text for the others. Markdown output is in one canonical spelling (`-` bullets,\n `*emphasis*`, `**strong**`, fenced code, one line per paragraph).\n- **`losses`** lists every construct that has no equivalent in the target, with\n its position: `line N` in Markdown, wiki markup and storage format, a JSON\n pointer (`/content/6/content/2`) in ADF. Each kind is also an `MD_LOSSY`\n warning. Words are kept wherever there are words to keep: a panel becomes a\n quote, a mention becomes `@name` text, a merged cell is unmerged with the cells\n it covered left empty.\n- **`roundTrip`**: the output is read back and compared with the input, block by\n block, as canonical Markdown. `differences` shows each block that changed, and\n whether a loss explains it. A change no loss explains fails the\n `roundTrip.blocks` check and warns `MD_ROUNDTRIP_MISMATCH`: that\'s a bug in the\n converter, so check the output before you send it.\n- **`lossless`** is true only when nothing was lost and every block came back the same.\n- **ADF output is validated against the ADF JSON schema** (Atlassian\'s\n `@atlaskit/adf-schema`, bundled) before it\'s returned, and storage output is\n read back as XML. Output that fails either is never returned; the command fails\n instead. ADF input the schema refuses is converted as far as it reads, with an\n `ADF_INPUT_INVALID` warning.\n\nReading and writing run in a worker thread, the conversion and the read back each\nwith 10 seconds and 1,024 MB; a 4 MiB document, the input limit, takes under\n4 seconds. A document whose emphasis or brackets would take far longer, or that\nnests past the stack, fails with `TIMEOUT` or `INVALID_INPUT` naming the step and\nthe limit.\n\nWhat Markdown means here: CommonMark plus GFM tables, task lists, strikethrough\nand bare-URL links. Raw HTML (other than `<br>`), link reference definitions and\nfootnotes aren\'t read; they\'re kept as text and reported as losses.\n\nKnown losses, by format:\n\n- **Wiki markup:** no task lists (written as `[ ]` / `[x]` text), no table\n alignment, no link or image titles, lists always start at 1, and a list item is\n one line, so a code block or second paragraph in one is joined with line breaks.\n Underline, colour, sub/superscript, citations, panels, mentions, attachments and\n other macros don\'t come back into Markdown. Text such as `(y)` that Jira shows as\n an emoticon, and a URL written as text, which Jira links, are reported too.\n- **ADF:** a quote can\'t hold a heading, table, task list or another quote, and a\n list item can\'t hold a heading, quote or table, so those are brought down and\n reported. Inline images become links; explicit left alignment is the default.\n Panels, expands, mentions, emoji, dates, statuses, smart links, decisions,\n attachments, layouts, extensions and merged cells don\'t come back.\n- **Storage format:** a list mixing tasks and ordinary items becomes a task list.\n Info, note, tip and warning panels, expand, layouts, page and user links,\n attachments, emoticons, colour, merged cells and other macros don\'t come back.\n Only XML\'s entities and HTML\'s common named ones (`&nbsp;`, `&mdash;` and so on)\n are read; any other is refused with `INVALID_INPUT`, as is XML that isn\'t\n well-formed, with its line and column.\n\nTo send the result, pass it to the area\'s own command: wiki markup as\n`toil jira issue create --description`, storage format as\n`toil confluence page create --body` (or `confluence-cloud`), and ADF as\n`fields.description` in a `toil jira-cloud issue create --input-file`. How each product\'s own renderer displays it hasn\'t\nbeen checked against a live instance.\n### `toil util openapi`: read an API description before calling it\n\nThree commands that read an OpenAPI 3.0, 3.1 or 3.2 or Swagger 2.0 document, in JSON\nor YAML, so you can call an endpoint right the first time, usually through\n`toil <area> api`. The document is a file in the workspace, `-` for stdin, or\n`--text` (`file` or `text` over MCP). Nothing is fetched: the official schemas\neach version is checked against are bundled.\n\n```bash\ntoil util openapi list jira-platform.json --tag Issues\ntoil util openapi list github.yaml --path pulls\ntoil util openapi show jira-platform.json --operation createIssue\ntoil util openapi show bitbucket.json --method POST --path /repositories/{workspace}/{repo_slug}/pullrequests --depth 1\ntoil util openapi example jira-platform.json --operation createIssue\ntoil util openapi example github.yaml --operation pulls/get --response 200\n```\n\n| Flag | Meaning |\n|------|---------|\n| `[file]` | The document: a file in the workspace, or `-` (or nothing) for stdin |\n| `--text <text>` | The document itself, instead of a file |\n| `--tag <tag>` | `list`: only operations with this tag (any case) |\n| `--path <text>` | `list`: only operations whose path contains this text. `show` and `example`: the path exactly as the document writes it, with `--method` |\n| `--operation <operationId>` | `show`, `example`: the operation, by its operationId |\n| `--method <method>` | `show`, `example`: the method, with `--path`, for an operation with no operationId |\n| `--depth <n>` | `show`: how many `$ref`s deep to expand schemas (default 3, at most 20) |\n| `--response <status>` | `example`: build that response\'s body (`200`, `201`, `default`) instead of the request body |\n| `--content-type <type>` | `example`: which of the body\'s content types (default: the first JSON one) |\n\nIn Git Bash on Windows, leave the leading `/` off `--path`\n(`--path repos/{owner}/{repo}/pulls`): the shell rewrites `/repos/...` into a file\npath. Both forms match.\n\n- **`list`** returns `{ document, count, operations: [{ method, path, operationId,\n summary, tags, deprecated }] }`.\n- **`show`** returns `{ document, operation, parameters, requestBody, responses,\n call, expansion }`. Each parameter has `name`, `in` (path, query, header, cookie),\n `required` and `schema`. The request body and each response have `contentTypes`,\n the `contentType` the `schema` is for (the first JSON one), and `schemaPointer`.\n Swagger 2.0\'s `body` and `formData` parameters come out as the request body, so\n both versions have one shape.\n- **Expanded schemas:** `$ref`s are replaced by what they point at, `--depth` refs\n deep, and an expanded one says where it came from in `x-toil-ref`. One left in\n place says why in `x-toil-stop`: `depth`, `circular` (it loops back), `external`\n (another file or a URL) or `broken`. `expansion.stopped` counts each. Expansion\n builds at most 250,000 objects and arrays per call (`expansion.nodes`) and copies\n at most 4,000,000 characters of the document\'s text (`expansion.chars`), since refs\n can fan out and each copies its whole target (three properties each referring to\n the next, twenty deep, is 3^20 copies). Past that, the rest stay in place as\n `depth`, `expansion.truncated` is true and an `OPENAPI_EXPANSION_TRUNCATED` warning\n says so. `example` generates at most 250,000 values, no more array items than\n that leaves room for, strings of at most 10,000 characters each, and at most 1,000,000\n characters in all, a document\'s own `const` and `enum` values included (a\n `minLength` or a pattern\'s `{n}` past that is cut; any value past the total is null). A cut-short example fails `example.valid` with\n `OPENAPI_EXAMPLE_TRUNCATED` and isn\'t validated. In 3.0 and\n Swagger 2.0 a `$ref`\'s sibling keys are dropped, as the spec says. From 3.1\n they\'re kept, over the target\'s keys.\n- **`example`** returns `{ document, operation, body, status, contentType,\n schemaPointer, example }`. The example is the smallest body the schema accepts:\n required properties only (read-only ones left out of a request, write-only ones\n out of a response), the first enum value, the lowest number in range, a string in\n the right format with placeholder values (`you@example.com`, `api.imagile.dev`),\n the first branch of a `oneOf`. It\'s minimal, not complete: Jira\'s `createIssue`\n gives `{}`, because its schema requires nothing. Use `show` to see the fields you\n want to add.\n\n#### Calling the endpoint with `<area> api`\n\n`show`\'s `call` is the operation as `<area> api` takes it: `method`, `path` (the\nserver\'s base path plus the operation\'s, with `{name}` for each of\n`pathParameters`), `query` (each required query parameter as `name=<name>`),\n`bodyFile`, `contentType` (set only when it isn\'t `application/json`), whether it\n`writes`, and the CLI line. Over MCP the same fields are `<area>_api`\'s inputs.\n\n```bash\ntoil util openapi show jira-platform.json --operation editIssue --select call\n# { "method": "PUT", "path": "/rest/api/2/issue/{issueIdOrKey}", "bodyFile": "body.json", "writes": true,\n# "cli": "toil <area> api PUT /rest/api/2/issue/{issueIdOrKey} --body-file body.json --allow-write", ... }\ntoil util openapi example jira-platform.json --operation editIssue --select example\ntoil jira api PUT /rest/api/2/issue/ABC-123 --body-file body.json --allow-write\n```\n\nSave the example as `body.json`, fill in the placeholders, and put the area the\ndocument describes for `<area>`. The path is relative to the connection\'s\n`baseUrl`: when `baseUrl` already ends with the server\'s base path (`/2.0` for\nBitbucket Cloud\'s), leave that part off. `call.unsupported` lists required header and\ncookie parameters, which `<area> api` doesn\'t send. `call` is null for a method it\ndoesn\'t send (OPTIONS, TRACE, QUERY).\n\n#### What every command checks\n\nEach one reads the whole document and checks it before answering, and\n`data.verified` says what it checked:\n\n| Check | What it is | Warning when it fails |\n|-------|------------|-----------------------|\n| `document.schema` | The document against the official schema for its version (Swagger 2.0, OpenAPI 3.0, 3.1 or 3.2), bundled. Every problem is in `document.problems` by JSON pointer (`/paths/~1pets/get/responses`), at most 50, with `problemCount` | `OPENAPI_INVALID` |\n| `refs.resolve` | Every local `$ref` points at something. Broken ones are in `document.refs.broken` as `{ at, ref }`, `at` being where the `$ref` sits | `OPENAPI_REF_BROKEN` |\n| `operations.uniqueIds` | No operationId is used twice | `OPENAPI_DUPLICATE_OPERATION_ID` |\n| `operations.pathParameters` | Every `{name}` in a path is declared as a path parameter | `OPENAPI_PATH_PARAMETER_MISSING` |\n| `example.valid` | `example` only: the generated body validates against its own schema, `$ref`s and all, before it\'s returned | `OPENAPI_EXAMPLE_INVALID` |\n| `input.complete` | The whole file was read | `INPUT_INCOMPLETE` |\n\nAn invalid document is still listed and shown, since real vendor documents aren\'t\nalways valid, but `verified.passed` is false. `document.refs.circular` lists each\nloop of references (a recursive schema), which is legal; nothing follows one\nforever. What can\'t be checked is reported, never assumed:\n\n- Checking the document against its schema gets 15 seconds and 1,536 MB, enough for a\n vendor spec of 13 MB, which takes about 4 seconds. Validating an example, and\n running the document\'s own `pattern`s, each get 2 seconds and 256 MB.\n A document too big to finish, a schema that branches too much (a diamond of\n `anyOf`s), a pattern that backtracks without end (`^(a+)+$`), or a document too\n deep for the stack leaves `document.schema`, `example.valid` or `example.patterns`\n unchecked, with which limit it hit (`UNVERIFIED`). So does a Node run with\n `--permission` and no `--allow-worker`.\n A document nested more than 256 levels is refused (`INVALID_INPUT`).\n- A YAML document is read in a worker thread with the same 15 seconds and 1,536 MB:\n YAML takes several times JSON\'s memory. Past either limit the command fails with\n `TIMEOUT` or `INVALID_INPUT` naming it; the same document as JSON reads in a fraction\n of both.\n- A `$ref` to another file or a URL isn\'t followed (`refs.external`, `UNVERIFIED`),\n and an example whose schema reaches one isn\'t validated.\n- The 3.1 and 3.2 schemas leave Schema Objects to the JSON Schema 2020-12 dialect,\n which isn\'t checked (`document.schemaObjects`, `UNVERIFIED`). Swagger 2.0 and 3.0\n documents are checked all the way down.\n- Some schemas have no value that satisfies them (two `allOf` branches that\n disagree, a property required and forbidden at once). The example is returned\n anyway, with `example.valid` failed at the pointer that doesn\'t fit, so you fill\n that value in by hand.\n\nA document that isn\'t an object, has no `openapi` or `swagger` field, declares a\nversion these commands don\'t read (OpenAPI 4, Swagger 1.2), or isn\'t valid JSON or\nYAML fails with `INVALID_INPUT`. So does an operation that isn\'t there (the fix names\nclose operationIds), `example` on an operation with no request body (pass\n`--response`), and a status or content type the operation doesn\'t list.\n\n### `toil util c4 render`, `toil util c4 mermaid`, `toil util c4 d2`\n\nOne view of a C4 architecture model: `render` draws it as SVG, `mermaid` writes it\nas Mermaid\'s C4 syntax (GitHub draws a ```` ```mermaid ```` block inline), and `d2`\nwrites it as D2 text. `render` lays the diagram out itself, with a layered layout\nmade for C4 views: people on the top row, the scope\'s children together inside\ntheir dashed boundary, and each relationship\'s label placed clear of the boxes.\nNothing is installed or run, and nothing goes over the network.\n\n```bash\ntoil util c4 render docs/c4/bookshop.c4.json --view containers --out containers.svg\ntoil util c4 mermaid docs/c4/bookshop.c4.json --view context\ncat model.json | toil util c4 d2 - --view components\n```\n\n| Flag | Meaning |\n|------|---------|\n| `[file]` | A JSON file holding the model, inside the workspace, or `-` (or nothing) for stdin |\n| `--text <text>` | The model itself, as a JSON string, instead of a file. Over MCP, `file` or `text` |\n| `--view <key>` | The view to draw. It can be left out when the model has only one |\n| `--out <file>` | `render` only: write the SVG to this new file inside the workspace instead of returning it. toil never overwrites a file |\n\nThe model:\n\n```json\n{\n "title": "Online bookshop",\n "people": [{ "id": "customer", "name": "Customer", "description": "Buys books" }],\n "systems": [{\n "id": "bookshop", "name": "Online Bookshop", "description": "Sells books at bookshop.imagile.dev",\n "containers": [\n { "id": "web", "name": "Web shop", "technology": "React",\n "components": [{ "id": "cart", "name": "Cart", "technology": "TypeScript" }] },\n { "id": "db", "name": "Database", "technology": "PostgreSQL", "database": true }\n ]\n }, { "id": "payments", "name": "Payment provider", "external": true }],\n "relationships": [{ "source": "customer", "destination": "web", "description": "Buys books using", "technology": "HTTPS" }],\n "views": [\n { "key": "context", "type": "systemContext", "scope": "bookshop" },\n { "key": "containers", "type": "container", "scope": "bookshop" },\n { "key": "components", "type": "component", "scope": "web", "include": ["*", "payments"] }\n ]\n}\n```\n\n- **Elements** are people and software systems at the top, containers inside a\n system, and components inside a container. Each has an `id`, a `name`, and\n optionally a `description`, a `technology` (containers and components) and\n `external: true`, which draws it grey. A container with `database: true` is drawn\n as a cylinder. Ids start with a letter and hold only letters, digits and\n underscores, and are unique across the whole model.\n- **Relationships** join any two elements, at any level: `source`, `destination`,\n and optionally `description` and `technology`.\n- **Views** have a `key`, a `type` (`systemContext`, `container` or `component`), a\n `scope` (a system for the first two, a container for `component`), an optional\n `title`, and an optional `include` list of ids. `"*"` in it stands for the default\n set, which is also what you get with no `include`: for `systemContext`, the scope\n and every person and system related to it; for `container`, the scope\'s\n containers inside a dashed boundary and what they relate to; for `component`, the\n scope\'s components and what they relate to.\n- A relationship is drawn between the nearest elements a view shows, so one between\n two containers shows up between their systems in a system context view. Model\n relationships at the most detailed level you know. One that ends on a view\'s own\n boundary from outside can\'t be drawn there; a `C4_RELATIONSHIP_NOT_DRAWN` warning\n in `meta.warnings` names it, unless that outside element already has a drawn\n relationship into the boundary.\n\nOutput: `{ view, type, title, elements, relationships, verified, format, svg }` for\n`render`, where `elements` lists the ids drawn and `relationships` counts the arrows.\nWith `--out`, `{ file, bytes }` take the place of `svg`, and `file` is the absolute\npath written. `mermaid` and `d2` return `text` in place of `svg`.\n\n`render` lays the view out down the page: arrows leave a box from its bottom, run\nstraight through any row they pass, and enter their target from the top, so they\nbend only in the gaps between rows. It checks its own drawing before returning it,\nand `data.verified` lists each check:\n\n| Check | What held |\n|-------|-----------|\n| `input.complete` | The whole file was read (unchecked for stdin and `--text`) |\n| `boxes.apart` | No two boxes overlap |\n| `children.inBoundary` | Every child is inside its dashed boundary, and nothing else is drawn over it (views with a boundary only) |\n| `edges.touchBoxes` | Every arrow starts on its source\'s border and ends on its target\'s |\n| `edges.clearOfBoxes` | No arrow passes behind a box it doesn\'t join |\n| `labels.clearOfBoxes` | No label covers a box |\n| `svg.wellFormed` | The SVG parses as XML and holds no character XML forbids. A control character in the model\'s text (other than tab and line breaks), U+FFFE, U+FFFF or a lone surrogate is drawn as U+FFFD |\n| `text.width` | Always `approximated`: text is measured with Helvetica\'s widths, which Arial shares |\n\nEach check that fails is one `C4_LAYOUT_CHECK` warning in `meta.warnings` naming\nthe first boxes or arrow involved and how many failed, and the first five are in\n`verified`, so a bad drawing is never returned without saying so. `mermaid` and\n`d2` check their own text instead: every element declared once (`text.elements`)\nand one line per arrow (`text.relationships`), failing as `C4_TEXT_CHECK`. Whether\nthe text draws is up to whatever renders it, and is reported as unchecked\n(`text.renders`, `UNVERIFIED`).\n\nLimits, each an `INVALID_INPUT` past it, before any work grows with it:\n\n- The model\'s JSON is at most 4 MiB.\n- A model holds at most 1,000 elements (people, systems, containers and components\n together), 2,000 relationships and 100 views.\n- `render` draws at most 100 boxes and 250 arrows in one view. Draw fewer with the\n view\'s `include` list, or split the view; `mermaid` and `d2` write a view of any\n size the model allows.\n\nThe layout runs in a worker thread with a 2 s deadline and 256 MB, past which it\'s\nstopped with `TIMEOUT`, or `INVALID_INPUT` for the memory; at the limits above it\ntakes well under a second and about 40 MB. Past about\n25 boxes, arrows cross more often and the drawing grows tall.\n\nA model with mistakes fails with `INVALID_INPUT` before anything is drawn. The\nmessage names each problem by its path in the model, such as\n`relationships[2].destination: no element has the id "warehose"`, and\n`error.details` lists them all. An unknown `--view` lists the keys the model has.\n\nA sample model, an online bookshop with all three views, is\n`docs/c4/bookshop.c4.json` in toil\'s source, and `docs/c4/busy.c4.json` is a busier\nview of 25 boxes.\n\n### `toil util owi map`\n\nMaps the output of toil\'s own work item and pull request commands to Open Work\nItems (OWI 0.2), the model in `docs/owi/spec.md` in toil\'s source, with its JSON\nSchema beside it in `docs/owi/schema.json`. It composes: each tracker is read by its own command,\nand this reads what they printed, whether piped, saved to a file, or appended one\nenvelope a line.\n\n```bash\ntoil jira issue search --jql "sprint in openSprints()" --fields "summary,status,issuetype,Story Points,Sprint" | toil util owi map\ntoil util owi map sprint-42.jsonl\ntoil util owi map changelog.json --key PAY-104\ntoil util owi map batch.json --field estimate=Custom.TeamPoints --field estimateUnit=points\ntoil util owi map issue.json --command "github issue get"\ntoil util owi map prs.jsonl --key-pattern "PAY-{n}=corp-jira" --author-kind release-bot=BOT\n```\n\n| Argument / flag | Meaning |\n|-----------------|---------|\n| `[file]` | A file inside the workspace. `-`, or no file and no `--text`, reads stdin |\n| `--text <text>` | The input itself, instead of a file |\n| `--command <name>` | The command whose data the input is, when it holds `data` without its envelope (`"jira issue search"`) |\n| `--key <key>` | The item a history belongs to, when its output doesn\'t say: `PAY-104`, or `imagile/payments-web#44` (a bare `44` takes the envelope\'s owner and repo) |\n| `--field <name=field>` | Point an OWI field at a field of your own, repeatable: `estimate`, `estimateUnit` (`points`, `hours` or `days`), `priority`, `type`, `team`, `dueDate` or `iteration`; and for GitHub without a board, `estimateLabel` (`size/{n}`) and `iterationDays` |\n| `--key-pattern <pattern=connection>` | Where work item keys in a pull request\'s title, branch and description point, repeatable, with `{n}` where the number is: `PAY-{n}=corp-jira`, `AB#{n}=corp-ado` |\n| `--author-kind <id=KIND>` | Set a pull request author\'s kind by hand, repeatable: `release-bot=BOT`, with `KIND` one of `HUMAN`, `AGENT` or `BOT`. It wins over every other signal |\n\nOver MCP the tool is `util_owi_map`, with `file` or `text`, and `command`, `key`,\n`field` (a list of `name=field`), `keyPattern` (a list of `pattern=connection`)\nand `authorKind` (a list of `id=KIND`).\n\n**What it reads**, by the command each envelope\'s `meta.command` names:\n\n- **Jira and Jira Cloud:** `issue search` and `issue get` (one key or several) for items,\n `issue history` for history.\n- **Azure DevOps and Azure DevOps Services:** `work-item get` and `work-item get-many` for items, `work-item history`\n for history, and `work-item iterations` for iteration dates. `work-item search`\n returns ids only and is skipped: map `work-item get-many` for those ids instead.\n- **GitHub:** `issue list`, `issue search` and `issue get` for issues,\n `project items` for the board\'s status, estimate and iteration, and\n `issue history` for history. Where no board gives a value, the issue\'s\n milestone is its iteration, a `points: N` label its estimate, and "Blocked by\n #n" or "Depends on #n" in its body a `blocks` link. Pull requests in an issue\n list or on a board are left out of the items with a warning.\n- **Pull requests:** `pr list` and `pr get` of `github`, `bitbucket`,\n `bitbucket-cloud`, `ado` and `ado-cloud`, as changes. A list is enough to rank\n what is open; `pr get --include reviews,checks,commits,files` adds what a list\n lacks, and a pull request in both is one change with the get\'s fields.\n\nPass one envelope, a JSON array of them, or one a line (`>>` appends each command\'s\noutput to one file). A Jira changelog and a GitHub timeline don\'t name their issue,\nso give `--key`, or wrap each as `{ "key": "PAY-104", "history": <envelope> }` in a\nfile holding several. Output from any other command is refused with\n`INVALID_INPUT` naming the ones that map.\n\nOutput:\n\n```json\n{\n "owi": "0.2",\n "count": 1,\n "items": [{\n "owi": "0.2",\n "id": "corp-jira:PAY-101",\n "source": { "area": "jira", "connection": "corp-jira", "key": "PAY-101", "command": "jira issue get" },\n "url": "https://jira.imagile.dev/browse/PAY-101",\n "type": "STORY", "typeName": "Story",\n "title": "Tokenise card numbers at the edge",\n "status": "In Progress", "statusCategory": "IN_PROGRESS",\n "estimate": { "value": 5, "unit": "points", "field": "Story Points" },\n "iteration": { "id": "42", "name": "Sprint 42", "path": null, "start": "2026-10-05T09:00:00.000Z", "end": "2026-10-16T17:00:00.000Z", "state": "current" },\n "parent": "corp-jira:PAY-100",\n "links": [{ "type": "blocks", "direction": "outward", "target": "corp-jira:PAY-102", "name": "blocks" }],\n "history": { "transitions": [{ "from": "To Do", "to": "In Progress", "fromCategory": "TODO", "toCategory": "IN_PROGRESS", "at": "2026-10-06T09:15:00.000Z", "by": { "id": "jsmith", "name": "J. Smith", "email": null } }], "iterations": [] },\n "unmapped": [],\n "native": { "jira issue get": { "key": "PAY-101", "fields": { "...": "..." } } }\n }],\n "changes": [],\n "histories": [],\n "unmapped": {},\n "skipped": [],\n "verified": { "passed": true, "checks": [{ "check": "items.schema", "status": "passed", "checked": 1, "failed": 0 }] }\n}\n```\n\n(Each item has every field in the spec; this one is shortened.) `count` is the\nnumber of items. A pull request is one of `changes`:\n\n```json\n{\n "owi": "0.2",\n "id": "github:imagile/payments-web#51",\n "source": { "area": "github", "connection": "github", "key": "imagile/payments-web#51", "command": "github pr get" },\n "repo": "imagile/payments-web",\n "title": "Retry the address lookup once",\n "branch": { "source": "claude/address-retry", "target": "main" },\n "state": "OPEN",\n "author": { "id": "ada-dev", "name": null, "email": null },\n "authorKind": "AGENT", "authorKindSource": "trailer", "authorKindSignal": "Co-Authored-By: Claude <you@example.com>",\n "reviewers": [], "reviews": [],\n "checks": "FAILING", "checksAt": "2026-10-09T08:10:00.000Z",\n "mergeable": true,\n "size": { "files": 2, "additions": 71, "deletions": 5 },\n "workItems": [],\n "created": "2026-10-08T09:00:00.000Z", "firstReviewAt": null, "approvedAt": null, "mergedAt": null,\n "unmapped": []\n}\n```\n\n- **`authorKind`** is `HUMAN`, `AGENT` or `BOT`, and `authorKindSource` says what\n set it, strongest first: an `override` (`--author-kind`), the `account` (GitHub\'s\n Bot type, a coding agent\'s account, a Bitbucket service account), an agent\'s\n Co-Authored-By `trailer` on a commit, an agent\'s `branch` prefix (`claude/`,\n `copilot/`, `codex/`), or `default` (`HUMAN`, nothing said otherwise).\n- **`workItems`** are the OWI ids the title, branch and description name: GitHub\'s\n own `#12` and Azure DevOps\' own `#2302` with no setup, and everything else by\n `--key-pattern`.\n- **`checks`** is `PASSING`, `FAILING`, `PENDING` or `NONE`, rolled up from the\n checks on the latest commit; null, with the reason in `unmapped`, when the input\n didn\'t hold them. The same goes for reviews, mergeability and size: each says\n which command fills it.\n\n- **`id`** is `<connection>:<native key>`, so items from two Jira sites never\n collide. Links, parents and children use the same ids.\n- **`statusCategory`** is `TODO`, `IN_PROGRESS`, `DONE` or `UNKNOWN`: from Jira\'s\n status category, Azure DevOps\' default states, and a GitHub board\'s Status\n options. A status with no known category is `UNKNOWN`, with an\n `OWI_UNKNOWN_STATE` warning naming it.\n- **`estimate`** comes from each tracker\'s default field: Story Points or Story\n point estimate in Jira (by the name the connection registers, never a fixed\n `customfield_` id), then the original estimate in hours; StoryPoints, Effort or\n Size in Azure DevOps, then OriginalEstimate; a board number field named\n Estimate, Size or Story Points in GitHub, else a label such as `points: 3`\n (`field` is then `label:points: 3`). `field` says which. Teams with a field of\n their own point `estimate` at it with `--field`, the same keys a dossier\'s\n `fields` uses; a GitHub team with its own estimate labels names them with\n `--field estimateLabel=size/{n}`.\n- **`iteration`** on a GitHub issue with no board value is its milestone: the\n due date is the end, and the previous milestone\'s due date the start (14 days\n before the end for the first, or `--field iterationDays=10` for every one).\n- **`unmapped`**, on each item, lists every field the record couldn\'t fill and\n why: a field `jira issue search` wasn\'t asked for, an iteration whose dates need\n `ado work-item iterations`, a GitHub issue with no milestone and no board. `data.unmapped`\n counts them by field, and an `OWI_UNMAPPED` warning sums them up. Nothing is\n guessed.\n- **`histories`** holds histories whose item wasn\'t in the input, by id, so they\n can be joined to items read earlier. **`skipped`** lists each document that\n wasn\'t mapped (a failed call, `work-item search`), each also an `OWI_SKIPPED` warning.\n- **`native`** keeps every source record as it came, keyed by command.\n- **`verified`:** every item, every history in `histories` and every change is\n validated against `docs/owi/schema.json` (`items.schema`, `histories.schema`,\n `changes.schema`) before it is returned; a failure is an `OWI_SCHEMA_INVALID` warning naming the item and the\n JSON pointer. The validation runs in a worker with a 2 s deadline per item, and\n one that can\'t finish is unchecked, never passed. `input.complete` checks the\n whole file was read.\n\nAt most 5,000 items, and 5,000 changes, are mapped in one call; past that the rest are left out with\nan `OWI_ITEMS_CAPPED` warning, so map them in another call. Input is at most\n64 MiB.\n\n### `toil util owi similar`\n\nFinds likely duplicate work items among Open Work Items, offline and deterministic:\nno model, no network, and the same answer every time. It reads what\n`toil util owi map` printed and asks no tracker itself, so it composes with any\nsearch. **Run it before filing or proposing a new item**, and before triaging one:\n`--query` with the title you were about to file says whether it already exists, in\nJira, Azure DevOps or GitHub.\n\n```bash\ntoil jira issue search --jql "project = PAY" | toil util owi map | toil util owi similar --query "Card payments time out at checkout"\ntoil util owi similar --input-file items.owi.json --item corp-jira:PAY-101 --limit 5\ntoil util owi similar --input-file items.owi.json --pairs --threshold 0.6\ntoil util owi similar items.owi.json --pairs --fields title,body\n```\n\n| Argument / flag | Meaning |\n|-----------------|---------|\n| `[file]`, `--input-file <path>` | The OWI records: a file inside the workspace. `-`, or no file and no `--text`, reads stdin |\n| `--text <text>` | The records themselves, instead of a file |\n| `--query <text>` | Rank every item against this text |\n| `--item <id>` | Rank the set against one of its items, by OWI id (`corp-jira:PAY-101`) |\n| `--pairs` | List likely duplicate pairs across the whole set, so items from different trackers are compared with each other |\n| `--limit <n>` | The most matches or pairs to return (default 10, up to 1000) |\n| `--threshold <score>` | The lowest score returned, 0 to 1 (default 0.35) |\n| `--fields <list>` | What to compare, separated by commas: `title`, `body`, `labels`, `parent` and `links` (default all) |\n\nA `--query` that nothing scores the threshold or more against returns no matches\nand an `OWI_SIMILAR_NO_MATCH` warning: there is no likely ticket for that text, so\nsuggest creating one. Don\'t lower `--threshold` to force a match. Matching work to a\nticket before starting it is `core.md`, **Ticket the work**.\n\nAsk exactly one of `--query`, `--item` and `--pairs`. Over MCP the tool is\n`util_owi_similar`, with `file` or `text`, one of `query`, `item` and `pairs`, and\n`limit`, `threshold` and `fields`.\n\n**What it reads:** the envelope `util owi map` printed, its `data`, a JSON array of\nOWI records (as Toil UI\'s cache holds them), or one record a line. A record needs an\n`id` and a `title`; one without either is skipped, listed in `data.skipped` and\nwarned about (`OWI_SIMILAR_SKIPPED`). Output from any other command is refused with\n`INVALID_INPUT`: map it first. An id that appears twice is read once\n(`OWI_SIMILAR_DUPLICATE_ID`).\n\nOutput, for `--item corp-jira:PAY-210 --limit 1`:\n\n```json\n{\n "mode": "item",\n "method": "Lexical similarity: BM25-weighted shared terms in titles and bodies, title character trigrams, and small boosts for shared labels, the same parent and a direct link. It measures shared words, not meaning, so a duplicate written in entirely different words scores low.",\n "fields": ["title", "body", "labels", "parent", "links"],\n "threshold": 0.35, "limit": 1,\n "query": null,\n "item": { "id": "corp-jira:PAY-210", "title": "Card payments time out at checkout", "source": { "area": "jira", "connection": "corp-jira", "key": "PAY-210", "command": "jira issue search" }, "url": "https://jira.imagile.dev/browse/PAY-210" },\n "items": 39, "count": 4,\n "matches": [{\n "id": "github:imagile/payments-web#51",\n "title": "Checkout times out when paying by card",\n "source": { "area": "github", "connection": "github", "key": "imagile/payments-web#51", "command": "github issue list" },\n "url": "https://ghe.imagile.dev/imagile/payments-web/issues/51",\n "score": 0.7211,\n "why": {\n "summary": "title terms checkout, time, card; body terms pay, 504, release, spinner, timeout, gateway; titles 72% alike by trigram; shared label checkout.",\n "titleTerms": ["checkout", "time", "card"],\n "bodyTerms": ["pay", "504", "release", "spinner", "timeout", "gateway"],\n "trigram": 0.7234,\n "labels": ["checkout"], "parent": null, "link": null, "titleOnly": false,\n "parts": { "terms": 0.4702, "trigram": 0.217, "labels": 0.0338, "parent": 0, "link": 0 }\n }\n }],\n "pairs": [], "search": null,\n "titleOnly": 19, "skipped": [],\n "verified": { "passed": true, "checks": [{ "check": "score.parts", "status": "passed", "checked": 1, "failed": 0 }, { "check": "score.meaning", "status": "approximated", "checked": 0, "failed": 0, "detail": "\u2026" }, { "check": "input.complete", "status": "passed", "checked": 1, "failed": 0 }] }\n}\n```\n\n`--pairs` returns `pairs` instead, each `{ score, a, b, why }` with `a` the lower id,\nand `search`: how many pairs were `compared`, and `skippedFeatures` (below).\n\n**How it scores**, so `why` can say exactly what drove each score:\n\n- **Terms (`titleTerms`, `bodyTerms`):** titles and bodies (Markdown, Jira wiki\n markup, HTML and ADF, read as plain text without their URLs) become lowercase\n words, with common English words dropped and plurals, `-ed` and `-ing` stemmed,\n each weighted by BM25 over the set, a title word worth twice a body word. Two\n items are compared by the cosine of those weights; a query by how much of its\n weight an item covers, a word in the title counting fully and one only in the\n body at most 0.7.\n- **Trigrams (`trigram`):** the character trigrams of the titles\' words, which\n catch typos and word forms the terms miss (`Recipt` and `Receipt`).\n- **Boosts (`labels`, `parent`, `link`):** up to 0.08 for shared labels (a rarer\n label counts more), 0.05 for the same parent and 0.1 for a direct link. Together\n they can\'t reach the default threshold on their own; at a threshold of 0.23 or\n less they can, and `OWI_SIMILAR_LOW_THRESHOLD` says so.\n\nThe score is 0.7 of the terms and 0.3 of the trigrams (all terms when titles aren\'t\nin `--fields`), plus the boosts, capped at 1 and rounded to four places. `parts`\nsays what each added, and they sum to the score. Results score at least the\nthreshold, best first, ties by id.\n\n**What it misses:** it measures shared words, not meaning. Two items that describe\none problem in entirely different words ("checkout hangs" and "payment page never\nloads") score low, which `method` and an `APPROXIMATED` warning say on every call.\nAn item with no body is compared on its title alone (`why.titleOnly`), and\n`OWI_SIMILAR_TITLE_ONLY` names those items: where the tracker holds a body, map them\nfrom a command that returns it. A body is read up to 5,000 terms\n(`OWI_SIMILAR_BODY_CUT`).\n\n**Large sets:** scoring runs in a worker with a 30 s deadline, so tens of thousands\nof items never hold the CLI or the MCP server. `--pairs` finds pairs through the\nterms, trigrams, labels and parents they share, so its work grows with what items\nhave in common, not with the square of the set. On a very large set the commonest\nof those stop being used to find pairs once a fixed budget is spent; `search`\ncounts them, and an `APPROXIMATED` warning says a pair sharing only those wasn\'t\ncompared. At most 50,000 records are scored in one call (`OWI_SIMILAR_CAPPED`), and\ninput is at most 64 MiB.\n\n**`verified`:** `score.parts` checks every returned score lies in 0 to 1 and equals\nits parts. With `--pairs`, `pairs.postings` holds the one shortcut the scorer takes\nto it: each pair\'s score is summed from the terms and trigrams it shares, and every\npair returned is worked out again in full, so the two must agree (where common\nfeatures were skipped, the summed score must not be the larger). A failure is an\n`OWI_SIMILAR_MISMATCH` warning. The same input always gives the same `data`.\n\nFrom a program, `findSimilar(items, request, options)` in `@imagile-dev/toil/api`\nranks OWI records you already hold the same way, in-process (`core.md`, **Using\ntoil from a program**).\n'
140352
140455
  };
140353
140456
  var skillPages = Object.fromEntries(
140354
140457
  Object.entries(skillFiles).flatMap(([file2, text4]) => file2 === "SKILL.md" ? [] : [[file2.slice(0, -3), text4]])
@@ -140633,10 +140736,10 @@ function parseStrictJson(text4) {
140633
140736
  }
140634
140737
  };
140635
140738
  const number4 = () => {
140636
- const match = /^-?(0|[1-9]\d*)(\.\d+)?([eE][+-]?\d+)?/.exec(src.slice(at10));
140637
- if (!match) fail2("Unexpected token");
140638
- at10 += match[0].length;
140639
- return Number(match[0]);
140739
+ const match2 = /^-?(0|[1-9]\d*)(\.\d+)?([eE][+-]?\d+)?/.exec(src.slice(at10));
140740
+ if (!match2) fail2("Unexpected token");
140741
+ at10 += match2[0].length;
140742
+ return Number(match2[0]);
140640
140743
  };
140641
140744
  const value2 = (path2) => {
140642
140745
  space2();
@@ -140851,9 +140954,9 @@ var EMAIL = /^[^@\s]+@[^@\s]+$/;
140851
140954
  var isRecord2 = (value2) => typeof value2 === "object" && value2 !== null && !Array.isArray(value2);
140852
140955
  var at = (path2, key6) => typeof key6 === "number" ? `${path2}[${key6}]` : path2 === "" ? key6 : `${path2}.${key6}`;
140853
140956
  function hasSecretUserinfo(url2) {
140854
- const match = /^([a-z][a-z0-9+.-]*):\/\/([^/@]*)@/i.exec(url2);
140855
- if (!match) return false;
140856
- return /^https?$/i.test(match[1]) || match[2].includes(":");
140957
+ const match2 = /^([a-z][a-z0-9+.-]*):\/\/([^/@]*)@/i.exec(url2);
140958
+ if (!match2) return false;
140959
+ return /^https?$/i.test(match2[1]) || match2[2].includes(":");
140857
140960
  }
140858
140961
  function stripUserinfo(url2) {
140859
140962
  return hasSecretUserinfo(url2) ? url2.replace(/^([a-z][a-z0-9+.-]*:\/\/)[^/@]*@/i, "$1") : url2;
@@ -141077,12 +141180,13 @@ function readPeople(raw3, areas2, error62, warn) {
141077
141180
  });
141078
141181
  return out;
141079
141182
  }
141080
- function hostMatches(settings, selector) {
141183
+ function hostMatches(settings, selector, siteApis) {
141081
141184
  const [host, port] = selector.toLowerCase().split(":");
141082
141185
  if (typeof settings.baseUrl === "string") {
141083
141186
  try {
141084
141187
  const url2 = new URL(settings.baseUrl);
141085
141188
  const actual = url2.port || (url2.protocol === "https:" ? "443" : url2.protocol === "http:" ? "80" : "");
141189
+ if (port === void 0 && host !== void 0 && Object.hasOwn(siteApis ?? {}, host) && apiHostOf(siteApis[host]) === url2.host.toLowerCase()) return true;
141086
141190
  return url2.hostname.toLowerCase() === host && (port === void 0 || actual === port);
141087
141191
  } catch {
141088
141192
  return false;
@@ -141091,6 +141195,28 @@ function hostMatches(settings, selector) {
141091
141195
  if (typeof settings.host === "string") return settings.host.toLowerCase() === host && (port === void 0 || String(settings.port ?? "") === port);
141092
141196
  return false;
141093
141197
  }
141198
+ function apiHostOf(url2) {
141199
+ try {
141200
+ return new URL(url2).host.toLowerCase();
141201
+ } catch {
141202
+ return void 0;
141203
+ }
141204
+ }
141205
+ function selectorHost(settings, siteApis) {
141206
+ if (!settings) return void 0;
141207
+ if (typeof settings.baseUrl === "string") {
141208
+ let host;
141209
+ try {
141210
+ host = new URL(settings.baseUrl).host.toLowerCase();
141211
+ } catch {
141212
+ return void 0;
141213
+ }
141214
+ const site = Object.entries(siteApis ?? {}).find(([, url2]) => apiHostOf(url2) === host);
141215
+ return site ? site[0] : host;
141216
+ }
141217
+ if (typeof settings.host === "string") return settings.host.toLowerCase() + (settings.port !== void 0 ? `:${String(settings.port)}` : "");
141218
+ return void 0;
141219
+ }
141094
141220
  function dossierContent(dossier) {
141095
141221
  return {
141096
141222
  ...dossier.$schema !== void 0 ? { $schema: dossier.$schema } : {},
@@ -141420,8 +141546,8 @@ function createDossierCatalog(o) {
141420
141546
  if (applied) warnings2.push(...sameName(scanned.files, applied.file.dossier.name));
141421
141547
  return { folder: f, ...repo ? { repo } : {}, ...applied ? { applied } : {}, candidates, warnings: warnings2 };
141422
141548
  };
141423
- const byHost = (dossier, area31, host) => {
141424
- const matches2 = connectionsOf(o.config, area31).filter((name3) => hostMatches(o.config.connections[name3], host));
141549
+ const byHost = (dossier, area31, host, config5 = o.config) => {
141550
+ const matches2 = connectionsOf(config5, area31).filter((name3) => hostMatches(config5.connections[name3], host, areaNames.get(area31)?.siteApis));
141425
141551
  if (matches2.length === 1) return matches2[0];
141426
141552
  if (matches2.length === 0) {
141427
141553
  throw new ToilError("NOT_CONFIGURED", `Dossier ${dossier.name} uses the ${area31} connection on ${host}, and you have no ${area31} connection with that host.`, {
@@ -141433,10 +141559,10 @@ function createDossierCatalog(o) {
141433
141559
  });
141434
141560
  };
141435
141561
  const sectionsFor = (dossier, area31, env) => [env === void 0 ? void 0 : ownValue(ownValue(dossier.environments, env), area31), ownValue(dossier.sections, area31)].filter((s) => s !== void 0);
141436
- const binding = (dossier, area31, env) => {
141562
+ const binding = (dossier, area31, env, config5) => {
141437
141563
  for (const section of sectionsFor(dossier, area31, env)) {
141438
141564
  if (typeof section.connection === "string") return { connection: section.connection, section };
141439
- if (typeof section.host === "string") return { connection: byHost(dossier, area31, section.host), host: section.host, section };
141565
+ if (typeof section.host === "string") return { connection: byHost(dossier, area31, section.host, config5), host: section.host, section };
141440
141566
  }
141441
141567
  return {};
141442
141568
  };
@@ -141725,8 +141851,8 @@ function gitEnv(env, call2) {
141725
141851
  return out;
141726
141852
  }
141727
141853
  function parseGitVersion(stdout) {
141728
- const match = /git version (\d+)\.(\d+)/.exec(stdout);
141729
- return match ? [Number(match[1]), Number(match[2])] : void 0;
141854
+ const match2 = /git version (\d+)\.(\d+)/.exec(stdout);
141855
+ return match2 ? [Number(match2[1]), Number(match2[2])] : void 0;
141730
141856
  }
141731
141857
  function envValue(env, name3, platform) {
141732
141858
  if (platform !== "win32") return env[name3];
@@ -142277,9 +142403,9 @@ function knownFolders(roots) {
142277
142403
  // src/skills/bundled.ts
142278
142404
  var SKILL_NAME = "toil";
142279
142405
  function frontmatterOf(text4) {
142280
- const match = /^---\n([\s\S]*?)\n---\n/.exec(text4);
142406
+ const match2 = /^---\n([\s\S]*?)\n---\n/.exec(text4);
142281
142407
  const out = {};
142282
- for (const line of match?.[1]?.split("\n") ?? []) {
142408
+ for (const line of match2?.[1]?.split("\n") ?? []) {
142283
142409
  const at10 = line.indexOf(": ");
142284
142410
  if (at10 > 0) out[line.slice(0, at10).trim()] = line.slice(at10 + 2).trim();
142285
142411
  }
@@ -142550,7 +142676,7 @@ function createNodeContext(o) {
142550
142676
  home: o.home,
142551
142677
  env: o.env,
142552
142678
  config: config5,
142553
- areas: o.areas.map((a) => ({ name: a.name, context: a.contextInputs ?? [] })),
142679
+ areas: o.areas.map((a) => ({ name: a.name, context: a.contextInputs ?? [], ...a.siteApis ? { siteApis: a.siteApis } : {} })),
142554
142680
  workspace,
142555
142681
  base: mcp ? workspace.dir : o.cwd,
142556
142682
  protect: ownFiles(o.home, o.cwd, o.globals.config),
@@ -145952,20 +146078,20 @@ function incrementNodeInspectorPort(args) {
145952
146078
  let debugOption;
145953
146079
  let debugHost = "127.0.0.1";
145954
146080
  let debugPort = "9229";
145955
- let match;
145956
- if ((match = arg.match(/^(--inspect(-brk)?)$/)) !== null) {
145957
- debugOption = match[1];
145958
- } else if ((match = arg.match(/^(--inspect(-brk|-port)?)=([^:]+)$/)) !== null) {
145959
- debugOption = match[1];
145960
- if (/^\d+$/.test(match[3])) {
145961
- debugPort = match[3];
146081
+ let match2;
146082
+ if ((match2 = arg.match(/^(--inspect(-brk)?)$/)) !== null) {
146083
+ debugOption = match2[1];
146084
+ } else if ((match2 = arg.match(/^(--inspect(-brk|-port)?)=([^:]+)$/)) !== null) {
146085
+ debugOption = match2[1];
146086
+ if (/^\d+$/.test(match2[3])) {
146087
+ debugPort = match2[3];
145962
146088
  } else {
145963
- debugHost = match[3];
146089
+ debugHost = match2[3];
145964
146090
  }
145965
- } else if ((match = arg.match(/^(--inspect(-brk|-port)?)=([^:]+):(\d+)$/)) !== null) {
145966
- debugOption = match[1];
145967
- debugHost = match[3];
145968
- debugPort = match[4];
146091
+ } else if ((match2 = arg.match(/^(--inspect(-brk|-port)?)=([^:]+):(\d+)$/)) !== null) {
146092
+ debugOption = match2[1];
146093
+ debugHost = match2[3];
146094
+ debugPort = match2[4];
145969
146095
  }
145970
146096
  if (debugOption && debugPort !== "0") {
145971
146097
  return `${debugOption}=${debugHost}:${parseInt(debugPort) + 1}`;
@@ -147441,9 +147567,9 @@ function topLevelWords(wiql) {
147441
147567
  depth--;
147442
147568
  i++;
147443
147569
  } else if (/[A-Za-z_@]/.test(ch)) {
147444
- const match = /^[A-Za-z_@][A-Za-z0-9_.@]*/.exec(wiql.slice(i));
147445
- if (depth === 0) words2.push({ word: match[0].toUpperCase(), index: i });
147446
- i += match[0].length;
147570
+ const match2 = /^[A-Za-z_@][A-Za-z0-9_.@]*/.exec(wiql.slice(i));
147571
+ if (depth === 0) words2.push({ word: match2[0].toUpperCase(), index: i });
147572
+ i += match2[0].length;
147447
147573
  } else {
147448
147574
  i++;
147449
147575
  }
@@ -148586,11 +148712,11 @@ var pipelineListRunsCommand = adoArea.command({
148586
148712
  }
148587
148713
  } else if (input4.name) {
148588
148714
  const wanted = input4.name.toLowerCase();
148589
- const match = (await listDefinitions(ctx, w)).find((d2) => d2.name.toLowerCase() === wanted);
148590
- if (!match) {
148715
+ const match2 = (await listDefinitions(ctx, w)).find((d2) => d2.name.toLowerCase() === wanted);
148716
+ if (!match2) {
148591
148717
  throw new ToilError("INVALID_INPUT", `Pipeline "${input4.name}" not found. Run 'toil ado pipeline list' to see available pipelines.`, { fix: "Check the name against toil ado pipeline list; it is matched ignoring case." });
148592
148718
  }
148593
- definitionId = match.id;
148719
+ definitionId = match2.id;
148594
148720
  }
148595
148721
  const filters = { definitionIds: definitionId !== void 0 ? [definitionId] : void 0, branchName: input4.branch, statusFilter: input4.status };
148596
148722
  return listBuilds(ctx, w, page2.cap !== void 0 ? { ...filters, page: page2 } : { ...filters, top: toInt(input4.top, "50") });
@@ -148941,7 +149067,7 @@ function queryOf(pairs, name3) {
148941
149067
  return query2;
148942
149068
  }
148943
149069
  var isJson = (contentType) => contentType !== null && /^application\/(?:[\w.+-]+\+)?json\b/i.test(contentType.trim());
148944
- var isText = (contentType) => contentType === null || /^(?:text\/|application\/(?:[\w.+-]+\+)?(?:json|xml)\b)/i.test(contentType.trim());
149070
+ var isText2 = (contentType) => contentType === null || /^(?:text\/|application\/(?:[\w.+-]+\+)?(?:json|xml)\b)/i.test(contentType.trim());
148945
149071
  function answer(bytes, contentType, name3, warn, download) {
148946
149072
  if (bytes.length === 0) return null;
148947
149073
  if (isJson(contentType)) {
@@ -148951,7 +149077,7 @@ function answer(bytes, contentType, name3, warn, download) {
148951
149077
  warn({ code: "API_NOT_JSON", message: `${name3}: the response said ${contentType} but isn't valid JSON, so data is the body as text.` });
148952
149078
  }
148953
149079
  }
148954
- const binary = !isText(contentType);
149080
+ const binary = !isText2(contentType);
148955
149081
  const kept = bytes.length > MAX_TEXT_BYTES ? bytes.subarray(0, MAX_TEXT_BYTES) : bytes;
148956
149082
  if (binary) {
148957
149083
  warn({
@@ -149149,9 +149275,9 @@ function topLevelWords2(wiql) {
149149
149275
  depth--;
149150
149276
  i++;
149151
149277
  } else if (/[A-Za-z_@]/.test(ch)) {
149152
- const match = /^[A-Za-z_@][A-Za-z0-9_.@]*/.exec(wiql.slice(i));
149153
- if (depth === 0) words2.push({ word: match[0].toUpperCase(), index: i });
149154
- i += match[0].length;
149278
+ const match2 = /^[A-Za-z_@][A-Za-z0-9_.@]*/.exec(wiql.slice(i));
149279
+ if (depth === 0) words2.push({ word: match2[0].toUpperCase(), index: i });
149280
+ i += match2[0].length;
149155
149281
  } else {
149156
149282
  i++;
149157
149283
  }
@@ -150229,10 +150355,10 @@ function pageParams(input4) {
150229
150355
  }
150230
150356
  async function getOne(ctx, path2, id9, what) {
150231
150357
  const rows = await alation(ctx, path2, { params: { id: id9, limit: 1 } });
150232
- const match = Array.isArray(rows) ? rows.find((r) => r.id === id9) : void 0;
150233
- const row = match ?? (Array.isArray(rows) ? rows[0] : void 0);
150358
+ const match2 = Array.isArray(rows) ? rows.find((r) => r.id === id9) : void 0;
150359
+ const row = match2 ?? (Array.isArray(rows) ? rows[0] : void 0);
150234
150360
  if (!row) throw new ToilError("NOT_FOUND", `${what} ${id9} not found`, { fix: `Check the ${what.toLowerCase()} ID exists in Alation and is visible to you.` });
150235
- if (!match) ctx.warn({ code: "ALATION_ID_MISMATCH", message: `Alation returned no ${what.toLowerCase()} with ID ${id9}; data is the first row it returned instead (ID ${JSON.stringify(row.id)}).` });
150361
+ if (!match2) ctx.warn({ code: "ALATION_ID_MISMATCH", message: `Alation returned no ${what.toLowerCase()} with ID ${id9}; data is the first row it returned instead (ID ${JSON.stringify(row.id)}).` });
150236
150362
  return row;
150237
150363
  }
150238
150364
 
@@ -152357,6 +152483,8 @@ var bitbucketCloudArea = defineArea({
152357
152483
  // Bitbucket Pipelines sets both on every step, so a pipeline needs no toil-specific context.
152358
152484
  fallbacks: { workspace: ["BITBUCKET_WORKSPACE"], repo: ["BITBUCKET_REPO_SLUG"] },
152359
152485
  examples: { baseUrl: "https://api.bitbucket.org/2.0", email: "you@example.com" },
152486
+ // bitbucket.org's API is on api.bitbucket.org, so a dossier's host: bitbucket.org selects that connection.
152487
+ siteApis: { "bitbucket.org": "https://api.bitbucket.org/2.0" },
152360
152488
  context: {
152361
152489
  // toil's own --workspace is the file-workspace flag and takes it wherever
152362
152490
  // it appears, so Bitbucket's workspace is spelt --ws, as splitio's is.
@@ -155091,23 +155219,23 @@ var librariesGetCommand = contrastArea.command({
155091
155219
  ],
155092
155220
  examples: [{ app: "abc12345-0000-0000-0000-000000000000", hash: "0f1e2d3c4b5a69788796a5b4c3d2e1f00f1e2d3c" }],
155093
155221
  run: async (input4, ctx) => {
155094
- let match;
155222
+ let match2;
155095
155223
  await paginate(
155096
155224
  { kind: "offset", startParam: "offset", limitParam: "limit", pageSize: BATCH, items: (body) => body },
155097
155225
  async (page2) => {
155098
155226
  const body = await contrast(ctx, apiPath`/applications/${input4.app}/libraries`, { limit: page2.limit, offset: page2.offset });
155099
155227
  const items = body.libraries ?? [];
155100
- match = items.find((item) => item.hash === input4.hash);
155101
- return { body: match || items.length < BATCH ? [] : items };
155228
+ match2 = items.find((item) => item.hash === input4.hash);
155229
+ return { body: match2 || items.length < BATCH ? [] : items };
155102
155230
  },
155103
155231
  { what: `Contrast libraries for application ${input4.app}` }
155104
155232
  );
155105
- if (!match) {
155233
+ if (!match2) {
155106
155234
  throw new ToilError("NOT_FOUND", `Library with hash "${input4.hash}" not found for application ${input4.app}`, {
155107
155235
  fix: `Check the hash with toil contrast app libraries ${input4.app}, and that the application ID is right.`
155108
155236
  });
155109
155237
  }
155110
- return match;
155238
+ return match2;
155111
155239
  }
155112
155240
  });
155113
155241
  var librariesCommands = [librariesListCommand, librariesGetCommand];
@@ -159392,12 +159520,12 @@ function isUrl(input4) {
159392
159520
  }
159393
159521
  function parseFileKey(input4) {
159394
159522
  if (isUrl(input4)) {
159395
- const match = /figma\.com\/(?:design|file)\/([A-Za-z0-9]+)/i.exec(input4);
159396
- if (!match?.[1]) {
159523
+ const match2 = /figma\.com\/(?:design|file)\/([A-Za-z0-9]+)/i.exec(input4);
159524
+ if (!match2?.[1]) {
159397
159525
  throw new ToilError("INVALID_INPUT", `Could not extract Figma file key from URL: ${input4}
159398
159526
  Expected format: https://www.figma.com/design/<file-key>/...`, { fix: FIX_KEY });
159399
159527
  }
159400
- return match[1];
159528
+ return match2[1];
159401
159529
  }
159402
159530
  return input4;
159403
159531
  }
@@ -159663,13 +159791,13 @@ var branchCommands = [branchCommand];
159663
159791
  import { isAbsolute as isAbsolute9 } from "node:path";
159664
159792
  var DIFF_LINE_LIMIT = 5e3;
159665
159793
  function parseHunkHeader(header) {
159666
- const match = header.match(/@@ -(\d+)(?:,(\d+))? \+(\d+)(?:,(\d+))? @@/);
159667
- if (!match) return { oldStart: 0, oldCount: 0, newStart: 0, newCount: 0 };
159794
+ const match2 = header.match(/@@ -(\d+)(?:,(\d+))? \+(\d+)(?:,(\d+))? @@/);
159795
+ if (!match2) return { oldStart: 0, oldCount: 0, newStart: 0, newCount: 0 };
159668
159796
  return {
159669
- oldStart: parseInt(match[1], 10),
159670
- oldCount: parseInt(match[2] ?? "1", 10),
159671
- newStart: parseInt(match[3], 10),
159672
- newCount: parseInt(match[4] ?? "1", 10)
159797
+ oldStart: parseInt(match2[1], 10),
159798
+ oldCount: parseInt(match2[2] ?? "1", 10),
159799
+ newStart: parseInt(match2[3], 10),
159800
+ newCount: parseInt(match2[4] ?? "1", 10)
159673
159801
  };
159674
159802
  }
159675
159803
  function parseDiff(rawDiff) {
@@ -160028,6 +160156,8 @@ var githubArea = defineArea({
160028
160156
  secrets: ["token"],
160029
160157
  // GitHub Actions sets both on every runner, so a workflow needs no toil-specific setup.
160030
160158
  fallbacks: { token: ["GITHUB_TOKEN"], baseUrl: ["GITHUB_API_URL"] },
160159
+ // github.com's API is on api.github.com, so a dossier's host: github.com selects that connection.
160160
+ siteApis: { "github.com": "https://api.github.com" },
160031
160161
  context: {
160032
160162
  owner: {
160033
160163
  description: "GitHub owner (user or org)",
@@ -161674,14 +161804,14 @@ async function triggerBuild(ctx, name3, params2) {
161674
161804
  ...hasParams ? { query: params2 } : {}
161675
161805
  });
161676
161806
  const location2 = res.headers.get("Location") ?? "";
161677
- const match = /\/queue\/item\/(\d+)\/?$/.exec(location2);
161678
- if (!match) {
161807
+ const match2 = /\/queue\/item\/(\d+)\/?$/.exec(location2);
161808
+ if (!match2) {
161679
161809
  throw new ToilError("HTTP", "Build queued but Jenkins did not return a Location header \u2014 cannot track queue item", {
161680
161810
  fix: `The build may be queued. Check it with toil jenkins pipeline runs ${name3} before triggering it again.`,
161681
161811
  details: { status: res.status }
161682
161812
  });
161683
161813
  }
161684
- return { queueItemId: parseInt(match[1], 10) };
161814
+ return { queueItemId: parseInt(match2[1], 10) };
161685
161815
  }
161686
161816
  function getQueueItem(ctx, queueItemId) {
161687
161817
  return jenkins(ctx, `/queue/item/${queueItemId}/api/json`);
@@ -165833,9 +165963,9 @@ function parseUnixTime(value2, flag) {
165833
165963
  }
165834
165964
  function parseChoice(value2, choices2, flag) {
165835
165965
  if (value2 === void 0) return void 0;
165836
- const match = choices2.find((c) => c.toLowerCase() === value2.trim().toLowerCase());
165837
- if (!match) throw invalid3(`Invalid ${flag} "${value2}". Expected one of: ${choices2.join(", ")}.`, `Pass ${flag} as one of: ${choices2.join(", ")}.`);
165838
- return match;
165966
+ const match2 = choices2.find((c) => c.toLowerCase() === value2.trim().toLowerCase());
165967
+ if (!match2) throw invalid3(`Invalid ${flag} "${value2}". Expected one of: ${choices2.join(", ")}.`, `Pass ${flag} as one of: ${choices2.join(", ")}.`);
165968
+ return match2;
165839
165969
  }
165840
165970
  function splitList(values3) {
165841
165971
  if (values3 === void 0) return void 0;
@@ -169510,9 +169640,9 @@ function parseYarnLock(content, lockFilePath, opts, packageJsonContent) {
169510
169640
  const packages = [];
169511
169641
  const seen = /* @__PURE__ */ new Set();
169512
169642
  const blockRegex = /^"?(@?[^@"\n][^"\n]*)@[^:]+:?\n\s+version "([^"]+)"/gm;
169513
- for (const match of content.matchAll(blockRegex)) {
169514
- const name3 = match[1].trim().replace(/^"|"$/g, "");
169515
- const version3 = match[2];
169643
+ for (const match2 of content.matchAll(blockRegex)) {
169644
+ const name3 = match2[1].trim().replace(/^"|"$/g, "");
169645
+ const version3 = match2[2];
169516
169646
  const key6 = `${name3}@${version3}`;
169517
169647
  if (seen.has(key6)) continue;
169518
169648
  seen.add(key6);
@@ -169529,10 +169659,10 @@ function parsePnpmLock(content, lockFilePath, opts, packageJsonContent) {
169529
169659
  const packages = [];
169530
169660
  const seen = /* @__PURE__ */ new Set();
169531
169661
  const blockRegex = /^\s{2}(\/?@?[^@\s/][^@\s]*)@(\d[^:\s]*):\s*\n((?:\s{4}[^\n]+\n)*)/gm;
169532
- for (const match of content.matchAll(blockRegex)) {
169533
- const name3 = match[1].replace(/^\//, "");
169534
- const version3 = match[2];
169535
- const attrs = match[3] ?? "";
169662
+ for (const match2 of content.matchAll(blockRegex)) {
169663
+ const name3 = match2[1].replace(/^\//, "");
169664
+ const version3 = match2[2];
169665
+ const attrs = match2[3] ?? "";
169536
169666
  const key6 = `${name3}@${version3}`;
169537
169667
  if (seen.has(key6)) continue;
169538
169668
  seen.add(key6);
@@ -169663,8 +169793,8 @@ function parsePomXml(content, filePath2, opts) {
169663
169793
  const managedVersions = extractDependencyManagement(content, props);
169664
169794
  const withoutMgmt = content.replace(/<dependencyManagement>[\s\S]*?<\/dependencyManagement>/gi, "");
169665
169795
  const packages = [];
169666
- for (const match of withoutMgmt.matchAll(/<dependency>([\s\S]*?)<\/dependency>/gi)) {
169667
- const inner = match[1];
169796
+ for (const match2 of withoutMgmt.matchAll(/<dependency>([\s\S]*?)<\/dependency>/gi)) {
169797
+ const inner = match2[1];
169668
169798
  const groupId = tag("groupId", inner);
169669
169799
  const artifactId = tag("artifactId", inner);
169670
169800
  if (!groupId || !artifactId) continue;
@@ -172966,7 +173096,7 @@ var owiMapCommand = defineCommand({
172966
173096
  var owiSimilarCommand = defineCommand({
172967
173097
  path: ["util", "owi", "similar"],
172968
173098
  description: "Find likely duplicate work items among OWI records: rank them against some text or one of them, or list likely duplicate pairs (local only, deterministic)",
172969
- toolDescription: "Finds likely duplicate work items among Open Work Item records (what util owi map returns: pass its envelope, its data, a JSON array of records, or one record a line, as file or text). Ask exactly one question: query ranks every item against some text (run it before filing or proposing a new item), item ranks the set against one of its items by OWI id (<connection>:<key>), and pairs lists likely duplicate pairs across the whole set, so items from Jira, Azure DevOps and GitHub are compared with each other. Scoring is lexical and deterministic, with no model and no network: BM25 over titles and bodies, title character trigrams (catching typos), and small boosts for shared labels, the same parent and a direct link. It finds shared words, not shared meaning. Returns { mode, method, fields, threshold, limit, query, item, items, count, matches, pairs, search, titleOnly, skipped, verified }: each match is { id, title, source, url, score, why } and each pair { score, a, b, why }, with why naming the title terms, body terms, trigram similarity, labels, parent and link that drove the score, and parts, what each added. Results score at least threshold (default 0.35), best first, at most limit (default 10). fields picks what is compared (title,body,labels,parent,links; default all). An item with no body is scored on its title alone, with a warning. Local only.",
173099
+ toolDescription: "Finds likely duplicate work items among Open Work Item records (what util owi map returns: pass its envelope, its data, a JSON array of records, or one record a line, as file or text). Ask exactly one question: query ranks every item against some text (run it before filing or proposing a new item), item ranks the set against one of its items by OWI id (<connection>:<key>), and pairs lists likely duplicate pairs across the whole set, so items from Jira, Azure DevOps and GitHub are compared with each other. Scoring is lexical and deterministic, with no model and no network: BM25 over titles and bodies, title character trigrams (catching typos), and small boosts for shared labels, the same parent and a direct link. It finds shared words, not shared meaning. Returns { mode, method, fields, threshold, limit, query, item, items, count, matches, pairs, search, titleOnly, skipped, verified }: each match is { id, title, source, url, score, why } and each pair { score, a, b, why }, with why naming the title terms, body terms, trigram similarity, labels, parent and link that drove the score, and parts, what each added. Results score at least threshold (default 0.35), best first, at most limit (default 10). fields picks what is compared (title,body,labels,parent,links; default all). An item with no body is scored on its title alone, with a warning. A query that nothing scores threshold or more against gets an OWI_SIMILAR_NO_MATCH warning: there is no likely ticket, so suggest creating one rather than lowering threshold to force a match. Local only.",
172970
173100
  input: external_exports.object({
172971
173101
  ...inputFields,
172972
173102
  query: external_exports.string().min(1).optional().describe("Rank every item against this text, such as the title of an item about to be filed"),
@@ -173261,14 +173391,120 @@ function parseTime2(text4, field4, endOfDay = false) {
173261
173391
 
173262
173392
  // src/connections/commands.ts
173263
173393
  init_errors();
173394
+
173395
+ // src/core/secret-input.ts
173396
+ init_errors();
173397
+ function characters(value2) {
173398
+ return Array.from(value2).length;
173399
+ }
173400
+ var plural2 = (n, one, many = `${one}s`) => `${n === 1 ? "a" : n} ${n === 1 ? one : many}`;
173401
+ function describeEnd(ws, end2) {
173402
+ if (ws === "") return null;
173403
+ const newlines = (ws.match(/\r\n|\r|\n/g) ?? []).length;
173404
+ const spaces2 = (ws.match(/ /g) ?? []).length;
173405
+ const tabs = (ws.match(/\t/g) ?? []).length;
173406
+ const total2 = characters(ws.replace(/\r\n/g, "\n"));
173407
+ if (newlines === total2) return plural2(newlines, `${end2} newline`);
173408
+ if (spaces2 === total2) return plural2(spaces2, `${end2} space`);
173409
+ if (tabs === total2) return plural2(tabs, `${end2} tab`);
173410
+ return plural2(total2, `${end2} whitespace character`);
173411
+ }
173412
+ var WHITESPACE3 = /\s/u;
173413
+ var QUOTES = [
173414
+ ['"', '"'],
173415
+ ["'", "'"],
173416
+ ["`", "`"],
173417
+ ["\u201C", "\u201D"],
173418
+ ["\u2018", "\u2019"]
173419
+ ];
173420
+ var PREFIX2 = /^(bearer|token)[ \t]+/i;
173421
+ function unwrap2(value2) {
173422
+ let inner = value2;
173423
+ let quoted2 = false;
173424
+ const pair = QUOTES.find(([open3, close]) => inner.length > open3.length + close.length && inner.startsWith(open3) && inner.endsWith(close));
173425
+ if (pair) {
173426
+ inner = inner.slice(pair[0].length, inner.length - pair[1].length);
173427
+ quoted2 = true;
173428
+ }
173429
+ const match2 = PREFIX2.exec(inner);
173430
+ const prefix = match2 && match2[0].length < inner.length ? `${match2[1]} ` : null;
173431
+ if (match2 && prefix) inner = inner.slice(match2[0].length);
173432
+ return { inner, quoted: quoted2, prefix };
173433
+ }
173434
+ function checkSecret2(raw3, rules) {
173435
+ const value2 = raw3.trim();
173436
+ if (value2 === "") {
173437
+ if (rules.empty === "keep") return { status: "empty", empty: "keep", message: "Kept the existing secret.", fix: null };
173438
+ if (rules.empty === "skip") return { status: "empty", empty: "skip", message: "Nothing was entered, so none is stored.", fix: null };
173439
+ return { status: "empty", empty: "required", message: "Nothing was entered, and this one is required.", fix: `Paste or type the secret, then press Enter.${rules.envVars?.length ? ` To define this connection with env vars instead, cancel and set ${rules.envVars.join(", ")}.` : ""}` };
173440
+ }
173441
+ const length = characters(value2);
173442
+ const lead = raw3.slice(0, raw3.length - raw3.trimStart().length);
173443
+ const trail = raw3.slice(raw3.trimEnd().length);
173444
+ const parts2 = [describeEnd(lead, "leading"), describeEnd(trail, "trailing")].filter((p) => p !== null);
173445
+ const removed = parts2.length ? parts2.join(" and ") : null;
173446
+ const { inner, quoted: quoted2, prefix } = unwrap2(value2);
173447
+ const breaks = /[\r\n]/.test(inner);
173448
+ const spaced = !rules.password && [...inner].some((c) => WHITESPACE3.test(c));
173449
+ if (breaks || spaced) {
173450
+ const what2 = rules.password ? "password" : "token";
173451
+ return {
173452
+ status: "refused",
173453
+ message: breaks ? "This has a line break in the middle, so the paste most likely took two lines. Nothing was stored." : `This has ${inner.includes(" ") ? "a tab" : "a space"} in the middle, so the paste most likely took more than the token. Nothing was stored.`,
173454
+ fix: `Copy just the ${what2}, on its own, and paste it again.`,
173455
+ length
173456
+ };
173457
+ }
173458
+ const what = quoted2 && prefix ? `the quotes and "${prefix}"` : quoted2 ? "the quotes" : prefix ? `"${prefix}"` : null;
173459
+ const wrapper = what ? {
173460
+ without: inner,
173461
+ withoutLength: characters(inner),
173462
+ what,
173463
+ question: quoted2 && prefix ? `This is in quotes and starts with "${prefix}". Store it without them? [Y/n]` : quoted2 ? "This is in quotes. Store it without them? [Y/n]" : `This starts with "${prefix}". Store it without that? [Y/n]`
173464
+ } : null;
173465
+ return { status: "ok", value: value2, length, removed, received: receivedLine(length, removed), wrapper };
173466
+ }
173467
+ function receivedLine(length, removed) {
173468
+ return `Received ${length} character${length === 1 ? "" : "s"}${removed ? ` (removed ${removed})` : ""}.`;
173469
+ }
173470
+ function answerYes(answer2) {
173471
+ const a = answer2.trim().toLowerCase();
173472
+ if (a === "" || a === "y" || a === "yes") return true;
173473
+ if (a === "n" || a === "no") return false;
173474
+ return void 0;
173475
+ }
173476
+ async function askCheckedSecret(prompt, question, key6, rules) {
173477
+ const note = (line) => prompt.note?.(line);
173478
+ for (; ; ) {
173479
+ const check2 = checkSecret2(await prompt.askSecret(question, `secret:${key6}`), rules);
173480
+ if (check2.status === "empty") {
173481
+ note(check2.message);
173482
+ if (check2.empty !== "required") return "";
173483
+ if (!prompt.canAskAgain) throw new ToilError("INVALID_INPUT", `${key6}: ${check2.message} Nothing was saved.`, { fix: check2.fix ?? "Enter it and try again." });
173484
+ continue;
173485
+ }
173486
+ if (check2.status === "refused") {
173487
+ note(`${check2.message} ${check2.fix}`);
173488
+ if (!prompt.canAskAgain) throw new ToilError("INVALID_INPUT", `${key6}: ${check2.message}`, { fix: check2.fix });
173489
+ continue;
173490
+ }
173491
+ note(check2.received);
173492
+ if (!check2.wrapper) return check2.value;
173493
+ for (; ; ) {
173494
+ const yes = answerYes(await prompt.ask(check2.wrapper.question, void 0, `unwrap:${key6}`));
173495
+ if (yes === true) {
173496
+ note(`Removed ${check2.wrapper.what}: ${check2.wrapper.withoutLength} character${check2.wrapper.withoutLength === 1 ? "" : "s"} left.`);
173497
+ return check2.wrapper.without;
173498
+ }
173499
+ if (yes === false) return check2.value;
173500
+ if (!prompt.canAskAgain) throw new ToilError("INVALID_INPUT", `The answer to "${check2.wrapper.question}" must be y or n.`, { fix: "Answer y to store it without that, or n to store it as entered." });
173501
+ }
173502
+ }
173503
+ }
173504
+
173505
+ // src/connections/commands.ts
173264
173506
  function connectionsCommands(areas2) {
173265
- const areaNamed = (name3) => {
173266
- const area31 = areas2.find((a) => a.name === name3);
173267
- if (area31) return area31;
173268
- throw new ToilError("INVALID_INPUT", `toil has no area named "${name3}".`, {
173269
- fix: areas2.length ? `Use one of: ${areas2.map((a) => a.name).join(", ")}.` : "This toil has no areas that take a connection yet."
173270
- });
173271
- };
173507
+ const areaNamed = (name3) => areaIn(areas2, name3);
173272
173508
  const add2 = defineConfigCommand({
173273
173509
  path: ["connections", "add"],
173274
173510
  description: "Set up a connection, asking for its settings and secret on the terminal",
@@ -173284,44 +173520,7 @@ function connectionsCommands(areas2) {
173284
173520
  { flags: "--area <area>", field: "area", description: "The area it connects to (asked for when left out)" }
173285
173521
  ],
173286
173522
  examples: [{ name: "corp-jira", area: "jira" }],
173287
- run: async (input4, ctx) => {
173288
- const { config: config5, secrets: secrets2, prompt } = access(ctx);
173289
- checkName(input4.name);
173290
- const path2 = config5.files.global;
173291
- const file2 = readConfigForEdit(path2);
173292
- if (file2.connections[input4.name]) {
173293
- throw new ToilError("INVALID_INPUT", `There's already a connection named "${input4.name}".`, {
173294
- fix: `Run toil connections login ${input4.name} to replace its secret, or toil connections remove ${input4.name} first.`
173295
- });
173296
- }
173297
- if (!prompt) throw needsTerminal("add", input4.name, input4.area ? areaNamed(input4.area) : void 0);
173298
- const area31 = areaNamed(input4.area ?? await prompt.ask(`Area (${areas2.map((a) => a.name).join(", ")})`, areas2.length === 1 ? areas2[0].name : void 0, "area"));
173299
- const { settings, secretValues } = await askSettings(prompt, area31);
173300
- const parsed = area31.connection.safeParse({ ...area31.defaults ?? {}, ...settings, ...secretValues });
173301
- if (!parsed.success) {
173302
- const keys2 = [...new Set(parsed.error.issues.map((i) => String(i.path[0] ?? "")).filter(Boolean))];
173303
- throw new ToilError("INVALID_INPUT", `Those settings aren't a valid ${area31.name} connection: check ${keys2.join(", ")}. Nothing was saved.`, {
173304
- fix: `Run toil connections add ${input4.name} again.`,
173305
- details: parsed.error.issues.map((i) => ({ path: i.path, message: i.message }))
173306
- });
173307
- }
173308
- const review = [
173309
- `area ${area31.name}`,
173310
- // An object or array setting (Jira's customFields) reads as JSON, not [object Object].
173311
- ...Object.entries(settings).map(([k, v]) => `${k} ${typeof v === "object" && v !== null ? JSON.stringify(v) : String(v)}`),
173312
- ...Object.keys(secretValues).map((k) => `${k} to the OS credential store`)
173313
- ].join(", ");
173314
- const answer2 = await prompt.ask(`Save ${input4.name} (${review})? y/n`, "y", "confirm");
173315
- if (!/^y(es)?$/i.test(answer2)) throw new ToilError("CANCELLED", "Nothing was saved.", { fix: `Run toil connections add ${input4.name} again.` });
173316
- const kept = await storeNew(secrets2, input4.name, secretValues, ctx.signal);
173317
- file2.connections[input4.name] = { area: area31.name, ...settings, ...kept };
173318
- const others = Object.keys(file2.connections).filter((n) => n !== input4.name && file2.connections[n].area === area31.name);
173319
- if (others.length === 0 && typeof file2.defaults[area31.name]?.connection !== "string") {
173320
- file2.defaults[area31.name] = { ...file2.defaults[area31.name] ?? {}, connection: input4.name };
173321
- }
173322
- writeConfigFile(path2, file2);
173323
- return { name: input4.name, area: area31.name, configFile: slashes3(path2), secrets: whereKept(kept) };
173324
- }
173523
+ run: async (input4, ctx) => addConnection(ctx, areas2, input4)
173325
173524
  });
173326
173525
  const login = defineConfigCommand({
173327
173526
  path: ["connections", "login"],
@@ -173347,7 +173546,8 @@ function connectionsCommands(areas2) {
173347
173546
  if (!prompt) throw needsTerminal("login", input4.name, area31);
173348
173547
  const entered = {};
173349
173548
  for (const key6 of keys2) {
173350
- const value2 = await prompt.askSecret(secretLabel(area31, key6), `secret:${key6}`);
173549
+ const rules = { password: area31.secretKinds[key6] === "password", empty: conn[key6] === void 0 ? "skip" : "keep" };
173550
+ const value2 = await askCheckedSecret(prompt, secretLabel(area31, key6), key6, rules);
173351
173551
  if (value2 !== "") entered[key6] = value2;
173352
173552
  }
173353
173553
  if (Object.keys(entered).length === 0) throw new ToilError("INVALID_INPUT", "Nothing was entered, so nothing changed.", { fix: `Run toil connections login ${input4.name} again.` });
@@ -173452,32 +173652,7 @@ function connectionsCommands(areas2) {
173452
173652
  writesLocal: false,
173453
173653
  args: [{ name: "name", field: "name", description: "Connection name" }],
173454
173654
  examples: [{ name: "jira" }],
173455
- run: async (input4, ctx) => {
173456
- const { config: config5, secrets: secrets2 } = access(ctx);
173457
- const settings = config5.connections[input4.name];
173458
- if (!settings) throw new ToilError("INVALID_INPUT", `There's no connection named "${input4.name}".`, { fix: "Run toil connections list to see the names." });
173459
- const area31 = areaNamed(settings.area);
173460
- const connection5 = await resolveConnection(config5, area31, input4.name, ctx.warn, secrets2, ctx.signal);
173461
- const host = hostOf(connection5, new Set(area31.secrets));
173462
- const probe2 = area31.request ? area31.probe?.(connection5) : void 0;
173463
- if (!probe2) {
173464
- ctx.warn({
173465
- code: "NOT_LIVE_TESTED",
173466
- message: `toil has no live check for ${area31.name} connections${area31.probe ? " set up like this one" : ""}, so nothing was sent. The settings are complete and the secret was read.`
173467
- });
173468
- return { name: input4.name, area: area31.name, host, live: false, authenticated: false, request: null };
173469
- }
173470
- const body = await apiRequest(area31, { fetch: ctx.fetch, signal: ctx.signal, connection: connection5 }, probe2.path, { as: probe2.as ?? "json", ...probe2.query ? { query: probe2.query } : {} });
173471
- if (probe2.accepts && !probe2.accepts(body)) {
173472
- throw new ToilError("AUTH", `${area31.name} answered GET ${probe2.path} for connection "${input4.name}" as an anonymous user, so its credential wasn't accepted.`, {
173473
- fix: `Run toil connections login ${input4.name} with a new credential, or replace the one its env var sets.`
173474
- });
173475
- }
173476
- if (probe2.authenticated === false) {
173477
- ctx.warn({ code: "NOT_AUTHENTICATED", message: `${area31.name} has no cheap read that needs the credential, so this test shows the host answers, not that the credential works.` });
173478
- }
173479
- return { name: input4.name, area: area31.name, host, live: true, authenticated: probe2.authenticated !== false, request: `GET ${probe2.path}` };
173480
- }
173655
+ run: async (input4, ctx) => testConnection(ctx, areas2, access(ctx).config, input4.name)
173481
173656
  });
173482
173657
  const writes = defineConfigCommand({
173483
173658
  path: ["connections", "writes"],
@@ -173547,6 +173722,82 @@ function connectionsCommands(areas2) {
173547
173722
  });
173548
173723
  return [add2, login, list7, remove, test, writes, setDefault];
173549
173724
  }
173725
+ function areaIn(areas2, name3) {
173726
+ const area31 = areas2.find((a) => a.name === name3);
173727
+ if (area31) return area31;
173728
+ throw new ToilError("INVALID_INPUT", `toil has no area named "${name3}".`, {
173729
+ fix: areas2.length ? `Use one of: ${areas2.map((a) => a.name).join(", ")}.` : "This toil has no areas that take a connection yet."
173730
+ });
173731
+ }
173732
+ async function addConnection(ctx, areas2, input4, options2 = {}) {
173733
+ const { config: config5, secrets: secrets2, prompt } = access(ctx);
173734
+ checkName(input4.name);
173735
+ const path2 = config5.files.global;
173736
+ const file2 = readConfigForEdit(path2);
173737
+ if (file2.connections[input4.name]) {
173738
+ throw new ToilError("INVALID_INPUT", `There's already a connection named "${input4.name}".`, {
173739
+ fix: `Run toil connections login ${input4.name} to replace its secret, or toil connections remove ${input4.name} first.`
173740
+ });
173741
+ }
173742
+ if (!prompt) throw needsTerminal("add", input4.name, input4.area ? areaIn(areas2, input4.area) : void 0);
173743
+ const area31 = areaIn(areas2, input4.area ?? await prompt.ask(`Area (${areas2.map((a) => a.name).join(", ")})`, areas2.length === 1 ? areas2[0].name : void 0, "area"));
173744
+ const { settings, secretValues } = await askSettings(prompt, area31, input4.name, options2.suggest);
173745
+ const parsed = area31.connection.safeParse({ ...area31.defaults ?? {}, ...settings, ...secretValues });
173746
+ if (!parsed.success) {
173747
+ const keys2 = [...new Set(parsed.error.issues.map((i) => String(i.path[0] ?? "")).filter(Boolean))];
173748
+ throw new ToilError("INVALID_INPUT", `Those settings aren't a valid ${area31.name} connection: check ${keys2.join(", ")}. Nothing was saved.`, {
173749
+ fix: `Run toil connections add ${input4.name} again.`,
173750
+ details: parsed.error.issues.map((i) => ({ path: i.path, message: i.message }))
173751
+ });
173752
+ }
173753
+ if (options2.host !== void 0 && !hostMatches({ ...area31.defaults ?? {}, ...settings }, options2.host, area31.siteApis)) {
173754
+ throw new ToilError("INVALID_INPUT", `That ${area31.name} connection isn't on ${options2.host}, the host the dossier selects, so it wouldn't be used. Nothing was saved.`, {
173755
+ fix: `Give a base URL on ${options2.host}${options2.suggest?.baseUrl ? `, such as ${options2.suggest.baseUrl}` : ""}.`
173756
+ });
173757
+ }
173758
+ const review = [
173759
+ `area ${area31.name}`,
173760
+ // An object or array setting (Jira's customFields) reads as JSON, not [object Object].
173761
+ ...Object.entries(settings).map(([k, v]) => `${k} ${typeof v === "object" && v !== null ? JSON.stringify(v) : String(v)}`),
173762
+ ...Object.keys(secretValues).map((k) => `${k} to the OS credential store`)
173763
+ ].join(", ");
173764
+ const answer2 = await prompt.ask(`Save ${input4.name} (${review})? y/n`, "y", "confirm");
173765
+ if (!/^y(es)?$/i.test(answer2)) throw new ToilError("CANCELLED", "Nothing was saved.", { fix: `Run toil connections add ${input4.name} again.` });
173766
+ const kept = await storeNew(secrets2, input4.name, secretValues, ctx.signal);
173767
+ file2.connections[input4.name] = { area: area31.name, ...settings, ...kept };
173768
+ const others = Object.keys(file2.connections).filter((n) => n !== input4.name && file2.connections[n].area === area31.name);
173769
+ if (others.length === 0 && typeof file2.defaults[area31.name]?.connection !== "string") {
173770
+ file2.defaults[area31.name] = { ...file2.defaults[area31.name] ?? {}, connection: input4.name };
173771
+ }
173772
+ writeConfigFile(path2, file2);
173773
+ return { name: input4.name, area: area31.name, configFile: slashes3(path2), secrets: whereKept(kept) };
173774
+ }
173775
+ async function testConnection(ctx, areas2, config5, name3) {
173776
+ const { secrets: secrets2 } = access(ctx);
173777
+ const settings = config5.connections[name3];
173778
+ if (!settings) throw new ToilError("INVALID_INPUT", `There's no connection named "${name3}".`, { fix: "Run toil connections list to see the names." });
173779
+ const area31 = areaIn(areas2, settings.area);
173780
+ const connection5 = await resolveConnection(config5, area31, name3, ctx.warn, secrets2, ctx.signal);
173781
+ const host = hostOf(connection5, new Set(area31.secrets));
173782
+ const probe2 = area31.request ? area31.probe?.(connection5) : void 0;
173783
+ if (!probe2) {
173784
+ ctx.warn({
173785
+ code: "NOT_LIVE_TESTED",
173786
+ message: `toil has no live check for ${area31.name} connections${area31.probe ? " set up like this one" : ""}, so nothing was sent. The settings are complete and the secret was read.`
173787
+ });
173788
+ return { name: name3, area: area31.name, host, live: false, authenticated: false, request: null };
173789
+ }
173790
+ const body = await apiRequest(area31, { fetch: ctx.fetch, signal: ctx.signal, connection: connection5 }, probe2.path, { as: probe2.as ?? "json", ...probe2.query ? { query: probe2.query } : {} });
173791
+ if (probe2.accepts && !probe2.accepts(body)) {
173792
+ throw new ToilError("AUTH", `${area31.name} answered GET ${probe2.path} for connection "${name3}" as an anonymous user, so its credential wasn't accepted.`, {
173793
+ fix: `Run toil connections login ${name3} with a new credential, or replace the one its env var sets.`
173794
+ });
173795
+ }
173796
+ if (probe2.authenticated === false) {
173797
+ ctx.warn({ code: "NOT_AUTHENTICATED", message: `${area31.name} has no cheap read that needs the credential, so this test shows the host answers, not that the credential works.` });
173798
+ }
173799
+ return { name: name3, area: area31.name, host, live: true, authenticated: probe2.authenticated !== false, request: `GET ${probe2.path}` };
173800
+ }
173550
173801
  function access(ctx) {
173551
173802
  if (!ctx.manage) throw new Error("A connections command ran without ctx.manage; define it with defineConfigCommand.");
173552
173803
  return ctx.manage;
@@ -173573,9 +173824,12 @@ function fileConnectionNames(config5) {
173573
173824
  return new Set(Object.keys(config5.connections).filter((name3) => Object.keys(config5.connections[name3]).some((key6) => config5.sources[`${name3}.${key6}`] === "global")));
173574
173825
  }
173575
173826
  }
173576
- function needsTerminal(command, name3, area31) {
173827
+ function envDefinition(name3, area31) {
173577
173828
  const keys2 = area31 ? Object.keys(area31.connection.shape) : ["<key>"];
173578
- const vars = [`${connectionEnvName(name3, "area")}=${area31?.name ?? "<area>"}`, ...keys2.map((k) => connectionEnvName(name3, k))];
173829
+ return [`${connectionEnvName(name3, "area")}=${area31?.name ?? "<area>"}`, ...keys2.map((k) => connectionEnvName(name3, k))];
173830
+ }
173831
+ function needsTerminal(command, name3, area31) {
173832
+ const vars = envDefinition(name3, area31);
173579
173833
  return new ToilError("INVALID_INPUT", `toil connections ${command} asks its questions on a terminal, and this isn't one.`, {
173580
173834
  fix: `Run it in a terminal, or define the connection with env vars instead: ${vars.join(", ")}.`
173581
173835
  });
@@ -173587,19 +173841,25 @@ function label(area31, key6) {
173587
173841
  function secretLabel(area31, key6) {
173588
173842
  return area31.secretKinds[key6] === "password" ? `${label(area31, key6)} [password]` : label(area31, key6);
173589
173843
  }
173590
- async function askSettings(prompt, area31) {
173844
+ async function askSettings(prompt, area31, name3, suggest = {}) {
173591
173845
  const shape = area31.connection.shape;
173592
173846
  const secretKeys = area31.secrets ?? [];
173593
173847
  const keys2 = Object.keys(shape).filter((k) => !secretKeys.includes(k)).sort((a, b) => Number(b === "baseUrl") - Number(a === "baseUrl"));
173594
173848
  const settings = {};
173595
173849
  for (const key6 of keys2) {
173596
173850
  const fallback = area31.defaults?.[key6] === void 0 ? void 0 : String(area31.defaults[key6]);
173597
- const answer2 = await prompt.ask(label(area31, key6), fallback, `setting:${key6}`);
173851
+ const offered = Object.hasOwn(suggest, key6) ? suggest[key6] : fallback;
173852
+ const answer2 = await prompt.ask(label(area31, key6), offered, `setting:${key6}`);
173598
173853
  if (answer2 !== "" && answer2 !== fallback) settings[key6] = coerce(shape[key6], answer2);
173599
173854
  }
173600
173855
  const secretValues = {};
173601
173856
  for (const key6 of secretKeys) {
173602
- const value2 = await prompt.askSecret(secretLabel(area31, key6), `secret:${key6}`);
173857
+ const required3 = area31.defaults?.[key6] === void 0 && shape[key6]?.safeParse(void 0).success === false;
173858
+ const value2 = await askCheckedSecret(prompt, secretLabel(area31, key6), key6, {
173859
+ password: area31.secretKinds[key6] === "password",
173860
+ empty: required3 ? "required" : "skip",
173861
+ envVars: envDefinition(name3, area31)
173862
+ });
173603
173863
  if (value2 !== "") secretValues[key6] = value2;
173604
173864
  }
173605
173865
  return { settings, secretValues };
@@ -173659,7 +173919,7 @@ function hostOf(conn, secretKeys) {
173659
173919
  var slashes3 = (path2) => path2.replace(/\\/g, "/");
173660
173920
 
173661
173921
  // src/dossiers/build.ts
173662
- import { rmSync as rmSync3 } from "node:fs";
173922
+ import { existsSync as existsSync11, rmSync as rmSync3 } from "node:fs";
173663
173923
  import { basename as basename10, join as join14 } from "node:path";
173664
173924
  init_errors();
173665
173925
  function dossierBuildCommands(areas2) {
@@ -173674,22 +173934,38 @@ function dossierBuildCommands(areas2) {
173674
173934
  const replaceField = external_exports.boolean().optional().describe("Change a value that is already set. Without it, a value already there is refused, naming it.");
173675
173935
  const init2 = defineConfigCommand({
173676
173936
  path: ["dossiers", "init"],
173677
- description: "Create a dossier in your own folder (~/.toil/dossiers)",
173678
- toolDescription: "Creates an empty dossier, ~/.toil/dossiers/<name>.json, for one body of work. Build it up with dossiers_add_repo, dossiers_link, dossiers_env and dossiers_field. A local write: it needs no allowWrite. Refuses a name already in your folder.",
173937
+ description: "Create a dossier in your own folder (~/.toil/dossiers), or with --shared in a repository for the team",
173938
+ toolDescription: "Creates an empty dossier for one body of work: ~/.toil/dossiers/<name>.json, or with shared, <repo>/.toil/dossiers/<name>.json in a repository's working tree (repo, else the folder's own repository) for everyone who clones it. A shared dossier selects connections by host, so a later link that names a connection records that connection's host instead. Build it up with dossiers_add_repo, dossiers_link, dossiers_env and dossiers_field. A local write: it needs no allowWrite. Refuses a name already there.",
173679
173939
  input: external_exports.object({
173680
173940
  name: external_exports.string().min(1).describe("The dossier name: lowercase letters, digits and single hyphens, e.g. payments"),
173681
- description: external_exports.string().min(1).optional().describe("One line saying what the body of work is")
173941
+ description: external_exports.string().min(1).optional().describe("One line saying what the body of work is"),
173942
+ shared: external_exports.boolean().optional().describe("Create it in a repository's .toil/dossiers for the team, selecting connections by host"),
173943
+ repo: external_exports.string().min(1).optional().describe("With shared: a working tree's root (default: the repository the folder is in)")
173682
173944
  }),
173683
173945
  writes: false,
173684
173946
  writesLocal: true,
173685
173947
  args: [{ name: "name", field: "name", description: "The dossier name, e.g. payments" }],
173686
- options: [{ flags: "--description <text>", field: "description", description: "One line saying what it covers" }],
173687
- examples: [{ name: "billing" }, { name: "billing", description: "Billing platform" }],
173948
+ options: [
173949
+ { flags: "--description <text>", field: "description", description: "One line saying what it covers" },
173950
+ { flags: "--shared", field: "shared", description: "Create it in a repository's .toil/dossiers, for the team" },
173951
+ { flags: "--repo <dir>", field: "repo", description: "With --shared: the working tree's root (default: this folder's repository)" }
173952
+ ],
173953
+ examples: [{ name: "billing" }, { name: "billing", description: "Billing platform" }, { name: "billing", shared: true, repo: "." }],
173688
173954
  run: async (input4, ctx) => {
173689
173955
  const { catalog } = access2(ctx);
173690
173956
  if (!CONNECTION_NAME.test(input4.name)) {
173691
173957
  throw new ToilError("INVALID_INPUT", `"${input4.name}" isn't a valid dossier name.`, { fix: "Use lowercase letters, digits and single hyphens, starting with a letter, e.g. payments." });
173692
173958
  }
173959
+ if (input4.repo !== void 0 && !input4.shared) {
173960
+ throw new ToilError("INVALID_INPUT", "--repo says which repository a shared dossier goes in, so it needs --shared.", { fix: `toil dossiers init ${input4.name} --shared --repo <dir>, or leave --repo out.` });
173961
+ }
173962
+ if (input4.shared) {
173963
+ const root = input4.repo ?? catalog.inspect(".").repo?.root;
173964
+ if (root === void 0) throw new ToilError("INVALID_INPUT", "A shared dossier goes in a repository, and this folder isn't in one.", { fix: "Pass --repo <dir>, a working tree's root, or run it inside the repository." });
173965
+ const dossier2 = { name: input4.name, ...input4.description ? { description: input4.description } : {}, repos: [], sections: {}, environments: {}, people: [] };
173966
+ const file3 = catalog.save(join14(catalog.repoFolder(root), `${input4.name}.json`), dossier2, "create");
173967
+ return { name: input4.name, file: file3, source: "repo", dossier: dossierContent(dossier2) };
173968
+ }
173693
173969
  const elsewhere = catalog.scan().files.filter((f) => f.dossier?.name === input4.name);
173694
173970
  const mine = elsewhere.find((f) => f.source === "user");
173695
173971
  if (mine) throw new ToilError("INVALID_INPUT", `You already have a dossier named "${input4.name}" (${forwardSlashes(mine.file)}).`, { fix: `Change it with toil dossiers link ${input4.name} ..., or choose another name.` });
@@ -173961,6 +174237,62 @@ function dossierBuildCommands(areas2) {
173961
174237
  return saved(ctx, catalog, file2, dossier, was !== input4.limit, { wipLimit: input4.limit });
173962
174238
  }
173963
174239
  });
174240
+ const describe5 = defineConfigCommand({
174241
+ path: ["dossiers", "describe"],
174242
+ description: "Rename one of your own dossiers, or change its description",
174243
+ toolDescription: "Renames one of your own dossiers (~/.toil/dossiers), or sets its one-line description, or both. A rename moves the file to ~/.toil/dossiers/<new name>.json with every section, repo, person and environment as it was, and is refused when you already have a dossier of that name. A checked-in or listed dossier is refused: copy it into your own folder with dossiers_import first. A local write: no allowWrite.",
174244
+ input: external_exports.object({
174245
+ dossier: dossierField,
174246
+ name: external_exports.string().min(1).optional().describe("The new name: lowercase letters, digits and single hyphens, e.g. card-payments"),
174247
+ description: external_exports.string().min(1).optional().describe("One line saying what the body of work is; replaces the one there")
174248
+ }),
174249
+ writes: false,
174250
+ writesLocal: true,
174251
+ args: [dossierArg],
174252
+ options: [
174253
+ { flags: "--name <name>", field: "name", description: "Rename it" },
174254
+ { flags: "--description <text>", field: "description", description: "One line saying what it covers" }
174255
+ ],
174256
+ examples: [{ dossier: "payments", description: "Card payments v2" }, { dossier: "payments", name: "card-payments", description: "Card payments v2" }],
174257
+ run: async (input4, ctx) => {
174258
+ const { catalog } = access2(ctx);
174259
+ if (input4.name === void 0 && input4.description === void 0) throw new ToilError("INVALID_INPUT", "Pass --name, --description, or both.", { fix: 'toil dossiers describe <dossier> --name <new name> --description "<one line>".' });
174260
+ const file2 = catalog.find(input4.dossier);
174261
+ if (file2.source !== "user") {
174262
+ throw new ToilError("INVALID_INPUT", `Dossier ${file2.dossier.name} is ${file2.source === "repo" ? "checked into a repository" : file2.source === "listed" ? "in a listed folder" : "a file outside your own folder"} (${forwardSlashes(file2.file)}), so it isn't yours to rename or describe.`, {
174263
+ fix: `Copy it into your own folder with toil dossiers import ${forwardSlashes(file2.file)}, then describe your copy.`
174264
+ });
174265
+ }
174266
+ const dossier = structuredClone(file2.dossier);
174267
+ const from = dossier.name;
174268
+ let description3;
174269
+ if (input4.description !== void 0) {
174270
+ description3 = input4.description.trim().replace(/\s*\r?\n\s*/g, " ");
174271
+ if (!description3) throw new ToilError("INVALID_INPUT", "The description is empty.", { fix: 'Give one line of text, e.g. --description "Card payments v2".' });
174272
+ dossier.description = description3;
174273
+ }
174274
+ const to = input4.name ?? from;
174275
+ if (to !== from) {
174276
+ if (!CONNECTION_NAME.test(to)) throw new ToilError("INVALID_INPUT", `"${to}" isn't a valid dossier name.`, { fix: "Use lowercase letters, digits and single hyphens, starting with a letter, e.g. card-payments." });
174277
+ const others = catalog.scan().files.filter((f) => f.dossier?.name === to);
174278
+ const mine = others.find((f) => f.source === "user");
174279
+ if (mine) throw new ToilError("INVALID_INPUT", `You already have a dossier named "${to}" (${forwardSlashes(mine.file)}).`, { fix: "Choose another name, or remove that one first with toil dossiers remove." });
174280
+ for (const other of others) ctx.warn({ code: "DOSSIER_DUPLICATE_NAME", message: `A dossier named "${to}" is also in ${forwardSlashes(other.file)} (${other.source}); yours takes precedence.` });
174281
+ dossier.name = to;
174282
+ }
174283
+ const changed = to !== from || file2.dossier.description !== dossier.description;
174284
+ if (to === from) return saved(ctx, catalog, file2, dossier, changed, { renamed: null, description: dossier.description ?? null });
174285
+ const target2 = catalog.userFile(to);
174286
+ if (!samePath(target2, file2.file) && existsSync11(target2)) {
174287
+ throw new ToilError("INVALID_INPUT", `${forwardSlashes(target2)} is already there, so dossier ${from} can't be renamed to "${to}".`, { fix: "Choose another name, or move that file out of your dossier folder first." });
174288
+ }
174289
+ const written = catalog.save(target2, dossier, samePath(target2, file2.file) ? "edit" : "create");
174290
+ if (!samePath(written, file2.file)) rmSync3(file2.file);
174291
+ const removed = credentialPaths(file2);
174292
+ if (removed.length) ctx.warn({ code: "DOSSIER_REMOTE_USERINFO", message: `Removed the credential from ${removed.join(", ")}; the file's remotes now carry none.` });
174293
+ return { name: to, file: written, source: "user", changed: true, renamed: { from, to, previousFile: forwardSlashes(file2.file) }, description: dossier.description ?? null, ...removed.length ? { credentialsRemoved: removed } : {} };
174294
+ }
174295
+ });
173964
174296
  const exportCommand = defineConfigCommand({
173965
174297
  path: ["dossiers", "export"],
173966
174298
  description: "Write a dossier for sharing: into a repository's .toil/dossiers, or to one file",
@@ -173985,7 +174317,7 @@ function dossierBuildCommands(areas2) {
173985
174317
  if (input4.repo === void 0 === (input4.file === void 0)) throw new ToilError("INVALID_INPUT", "Pass exactly one of --repo and --file.", { fix: "toil dossiers export <name> --repo <dir>, or --file <path>." });
173986
174318
  const source2 = catalog.find(input4.dossier);
173987
174319
  if (via !== "cli") refuseWritesBindings(catalog, config5, areas2, source2.dossier, "export");
173988
- const { dossier, hosts, droppedPaths } = forSharing(source2.dossier, config5);
174320
+ const { dossier, hosts, droppedPaths } = forSharing(source2.dossier, config5, areas2);
173989
174321
  const target2 = input4.repo !== void 0 ? join14(catalog.repoFolder(input4.repo), `${dossier.name}.json`) : catalog.pathFor(input4.file, "The export file");
173990
174322
  const file2 = catalog.save(target2, dossier, input4.replace ? "replace" : "create");
173991
174323
  return { name: dossier.name, file: file2, hosts, droppedPaths, dossier: dossierContent(dossier) };
@@ -174094,8 +174426,8 @@ function dossierBuildCommands(areas2) {
174094
174426
  return { name: input4.name, file: forwardSlashes(mine.file), deleted: true };
174095
174427
  }
174096
174428
  });
174097
- return [init2, addRepo, link, env, field4, person3, wipLimit, exportCommand, importCommand, unlink, remove];
174098
- async function changeSection({ catalog, config: config5, via }, ctx, area31, envName2, input4, makeDefault2) {
174429
+ return [init2, addRepo, link, env, field4, person3, wipLimit, describe5, exportCommand, importCommand, unlink, remove];
174430
+ async function changeSection({ catalog, config: config5, via, prompt }, ctx, area31, envName2, input4, makeDefault2) {
174099
174431
  const file2 = catalog.find(input4.dossier);
174100
174432
  const before2 = file2.dossier;
174101
174433
  const dossier = structuredClone(before2);
@@ -174108,6 +174440,7 @@ function dossierBuildCommands(areas2) {
174108
174440
  if (input4.connection !== void 0) {
174109
174441
  const conn = config5.connections[input4.connection];
174110
174442
  if (!conn || conn.area !== area31.name) throw refuse2(`You have no ${area31.name} connection named "${input4.connection}"`, `Run toil connections list --area ${area31.name} to see yours.`);
174443
+ if (file2.source !== "user") input4 = await sharedBinding(ctx, prompt, file2.file, area31, input4.connection, conn, input4);
174111
174444
  }
174112
174445
  const bound = typeof section.connection === "string" ? `connection ${section.connection}` : typeof section.host === "string" ? `host ${section.host}` : void 0;
174113
174446
  const wanted = input4.connection !== void 0 ? `connection ${input4.connection}` : input4.host !== void 0 ? `host ${input4.host.toLowerCase()}` : void 0;
@@ -174162,7 +174495,25 @@ function dossierBuildCommands(areas2) {
174162
174495
  function access2(ctx) {
174163
174496
  if (!ctx.manage) throw new Error("A dossiers command ran without ctx.manage; define it with defineConfigCommand.");
174164
174497
  if (!ctx.manage.dossiers) throw new ToilError("NOT_CONFIGURED", "Dossiers are not available here.", { fix: "Run toil dossiers from the CLI or toil mcp." });
174165
- return { catalog: ctx.manage.dossiers, config: ctx.manage.config, via: ctx.manage.via };
174498
+ return { catalog: ctx.manage.dossiers, config: ctx.manage.config, via: ctx.manage.via, prompt: ctx.manage.prompt };
174499
+ }
174500
+ async function sharedBinding(ctx, prompt, file2, area31, name3, conn, input4) {
174501
+ const host = selectorHost(conn, area31.siteApis);
174502
+ const shared = `${forwardSlashes(file2)} is shared`;
174503
+ if (host === void 0) {
174504
+ ctx.warn({ code: "DOSSIER_CONNECTION_SHARED", message: `${shared}, but connection ${name3} has no host to record, so the dossier names it: that works only for readers with a ${area31.name} connection called ${name3}.` });
174505
+ return input4;
174506
+ }
174507
+ if (prompt) {
174508
+ const answer2 = await prompt.ask(`${shared}, and teammates name their connections differently. Record host ${host} instead of connection ${name3}? y/n`, "y", "confirm");
174509
+ if (!/^y(es)?$/i.test(answer2)) {
174510
+ ctx.warn({ code: "DOSSIER_CONNECTION_SHARED", message: `${shared} and names connection ${name3}, which works only for readers with a ${area31.name} connection called ${name3}; "host": "${host}" works for everyone.` });
174511
+ return input4;
174512
+ }
174513
+ } else {
174514
+ ctx.warn({ code: "DOSSIER_HOST_RECORDED", message: `${shared}, so it records host ${host}, which selects each reader's own ${area31.name} connection there, rather than connection ${name3}.` });
174515
+ }
174516
+ return { ...input4, connection: void 0, host };
174166
174517
  }
174167
174518
  function saved(ctx, catalog, file2, dossier, changed, extra) {
174168
174519
  const removed = credentialPaths(file2);
@@ -174226,13 +174577,13 @@ function hostWarnings(catalog, dossier, area31, env) {
174226
174577
  return [{ code: e.code === "NOT_CONFIGURED" ? "DOSSIER_HOST_UNMATCHED" : "DOSSIER_HOST_AMBIGUOUS", message: e.message }];
174227
174578
  }
174228
174579
  }
174229
- function forSharing(source2, config5) {
174580
+ function forSharing(source2, config5, areas2 = []) {
174230
174581
  const dossier = structuredClone(source2);
174231
174582
  const hosts = [];
174232
174583
  const share = (area31, env, section) => {
174233
174584
  if (typeof section.connection !== "string") return;
174234
174585
  const name3 = section.connection;
174235
- const host = hostOf2(config5.connections[name3]);
174586
+ const host = selectorHost(config5.connections[name3], areas2.find((a) => a.name === area31)?.siteApis);
174236
174587
  if (!host) {
174237
174588
  throw new ToilError("INVALID_INPUT", `Dossier ${dossier.name}'s ${env ? `${env} ` : ""}${area31} section selects connection ${name3}, ${config5.connections[name3] ? "which has no host to share" : "which isn't one of yours"}.`, {
174238
174589
  fix: `Select it by host instead (toil dossiers link ${dossier.name} ${area31} --host <host> --replace), or remove the binding.`
@@ -174252,18 +174603,6 @@ function forSharing(source2, config5) {
174252
174603
  });
174253
174604
  return { dossier, hosts, droppedPaths };
174254
174605
  }
174255
- function hostOf2(settings) {
174256
- if (!settings) return void 0;
174257
- if (typeof settings.baseUrl === "string") {
174258
- try {
174259
- return new URL(settings.baseUrl).host.toLowerCase();
174260
- } catch {
174261
- return void 0;
174262
- }
174263
- }
174264
- if (typeof settings.host === "string") return settings.host.toLowerCase() + (settings.port !== void 0 ? `:${String(settings.port)}` : "");
174265
- return void 0;
174266
- }
174267
174606
  function unresolved(catalog, config5, dossier) {
174268
174607
  const out = [];
174269
174608
  const look2 = (area31, env, section) => {
@@ -174283,6 +174622,10 @@ function unresolved(catalog, config5, dossier) {
174283
174622
  return out;
174284
174623
  }
174285
174624
 
174625
+ // src/dossiers/onboard.ts
174626
+ import { dirname as dirname8 } from "node:path";
174627
+ init_errors();
174628
+
174286
174629
  // src/dossiers/commands.ts
174287
174630
  init_errors();
174288
174631
  function dossiersCommands(areas2) {
@@ -174371,14 +174714,9 @@ function dossiersCommands(areas2) {
174371
174714
  ctx.setExitCode(1);
174372
174715
  return { name: input4.dossier ?? null, file: null, source: null, ok: false, problems: details.map((d2) => ({ level: "error", code: "DOSSIER_INVALID", path: d2.path, message: d2.message })), message: broken.message };
174373
174716
  }
174374
- const problems = [...target2.problems.map((p) => p.code === "DOSSIER_REMOTE_USERINFO" ? { ...p, level: "error" } : p), ...bindingProblems(catalog, ctx.manage.config, areas2, target2)];
174375
- const others = catalog.scan(input4.cwd).files.filter((f) => f.dossier?.name === target2.dossier.name && f.file !== target2.file);
174376
- for (const other of others) {
174377
- problems.push({ level: "warning", code: "DOSSIER_DUPLICATE_NAME", path: "name", message: `A dossier with the same name is also in ${forwardSlashes(other.file)} (${other.source}).` });
174378
- }
174379
- const ok2 = !problems.some((p) => p.level === "error");
174717
+ const { ok: ok2, problems } = checkDossier10(catalog, ctx.manage.config, areas2, target2, input4.cwd);
174380
174718
  if (!ok2) ctx.setExitCode(1);
174381
- return { name: target2.dossier.name, file: forwardSlashes(target2.file), source: target2.source, ok: ok2, problems: problems.map(problemOut) };
174719
+ return { name: target2.dossier.name, file: forwardSlashes(target2.file), source: target2.source, ok: ok2, problems };
174382
174720
  }
174383
174721
  });
174384
174722
  const context = defineConfigCommand({
@@ -174398,6 +174736,14 @@ function dossiersCommands(areas2) {
174398
174736
  });
174399
174737
  return [list7, show, check2, context];
174400
174738
  }
174739
+ function checkDossier10(catalog, config5, areas2, target2, cwd) {
174740
+ const problems = [...target2.problems.map((p) => p.code === "DOSSIER_REMOTE_USERINFO" ? { ...p, level: "error" } : p), ...bindingProblems(catalog, config5, areas2, target2)];
174741
+ const others = catalog.scan(cwd).files.filter((f) => f.dossier?.name === target2.dossier.name && f.file !== target2.file);
174742
+ for (const other of others) {
174743
+ problems.push({ level: "warning", code: "DOSSIER_DUPLICATE_NAME", path: "name", message: `A dossier with the same name is also in ${forwardSlashes(other.file)} (${other.source}).` });
174744
+ }
174745
+ return { ok: !problems.some((p) => p.level === "error"), problems: problems.map(problemOut) };
174746
+ }
174401
174747
  function dossiersOf(ctx) {
174402
174748
  if (!ctx.manage) throw new Error("A dossiers command ran without ctx.manage; define it with defineConfigCommand.");
174403
174749
  if (!ctx.manage.dossiers) throw new ToilError("NOT_CONFIGURED", "Dossiers are not available here.", { fix: "Run toil dossiers from the CLI or toil mcp." });
@@ -174453,18 +174799,27 @@ function resolvedAreas(catalog, config5, areas2, applied) {
174453
174799
  }
174454
174800
  function bindingProblems(catalog, config5, areas2, file2) {
174455
174801
  const dossier = file2.dossier;
174456
- const known = new Set(areas2.map((a) => a.name));
174802
+ const byName4 = new Map(areas2.map((a) => [a.name, a]));
174457
174803
  const problems = [];
174458
174804
  const sections = [
174459
174805
  ...Object.keys(dossier.sections).map((area31) => [area31, area31, void 0]),
174460
174806
  ...Object.entries(dossier.environments).flatMap(([env, byArea]) => Object.keys(byArea).map((area31) => [area31, `environments.${env}.${area31}`, env]))
174461
174807
  ];
174462
174808
  for (const [area31, path2, env] of sections) {
174463
- if (!known.has(area31)) continue;
174809
+ if (!byName4.has(area31)) continue;
174464
174810
  const section = env === void 0 ? dossier.sections[area31] : dossier.environments[env][area31];
174465
174811
  let name3;
174466
174812
  if (typeof section.connection === "string") {
174467
174813
  const conn = config5.connections[section.connection];
174814
+ if (file2.source !== "user" && conn?.area === area31) {
174815
+ const host = selectorHost(conn, byName4.get(area31).siteApis);
174816
+ problems.push({
174817
+ level: "warning",
174818
+ code: "DOSSIER_CONNECTION_SHARED",
174819
+ path: `${path2}.connection`,
174820
+ message: `This shared dossier selects connection "${section.connection}" by name, which works only for readers who named theirs the same. Select it by host instead: ${host ? `"host": "${host}"` : `"host" set to the connection's host`} (toil dossiers ${env ? `env ${dossier.name} ${env}` : `link ${dossier.name}`} ${area31} --host ${host ?? "<host>"} --replace).`
174821
+ });
174822
+ }
174468
174823
  if (!conn || conn.area !== area31) {
174469
174824
  problems.push({ level: "error", code: "DOSSIER_UNKNOWN_CONNECTION", path: `${path2}.connection`, message: `You have no ${area31} connection named "${section.connection}".` });
174470
174825
  continue;
@@ -174472,7 +174827,7 @@ function bindingProblems(catalog, config5, areas2, file2) {
174472
174827
  name3 = section.connection;
174473
174828
  } else if (typeof section.host === "string") {
174474
174829
  try {
174475
- name3 = catalog.binding({ ...dossier, sections: { [area31]: section }, environments: {} }, area31, void 0).connection;
174830
+ name3 = catalog.binding({ ...dossier, sections: { [area31]: section }, environments: {} }, area31, void 0, config5).connection;
174476
174831
  } catch (err) {
174477
174832
  const e = toToilError(err);
174478
174833
  problems.push({ level: "error", code: e.code === "NOT_CONFIGURED" ? "DOSSIER_HOST_UNMATCHED" : "DOSSIER_HOST_AMBIGUOUS", path: `${path2}.host`, message: e.message });
@@ -174500,6 +174855,226 @@ function contextOut(selection) {
174500
174855
  };
174501
174856
  }
174502
174857
 
174858
+ // src/dossiers/onboard.ts
174859
+ function dossierOnboardCommands(areas2) {
174860
+ const onboard = defineConfigCommand({
174861
+ path: ["dossiers", "onboard"],
174862
+ description: "Set up this repo: match each area of its dossier to your connections, add the ones you lack, then check it and test each",
174863
+ input: external_exports.object({
174864
+ dossier: external_exports.string().min(1).optional().describe("A dossier name, or the path to a dossier file. Defaults to the dossier that applies to the folder."),
174865
+ cwd: external_exports.string().min(1).optional().describe("The folder to look from; its repository decides which checked-in dossiers apply. Defaults to the workspace."),
174866
+ plan: external_exports.boolean().optional().describe("Ask nothing and add no connection: report what each area needs, then check and test what is there. A pin still applies."),
174867
+ pin: external_exports.array(external_exports.string().min(1)).optional().describe("Where several of your connections match, the one your own copy of the dossier uses: area=connection for every section of the area, or a section's key path (environments.prod.github=connection) for that one")
174868
+ }),
174869
+ writes: false,
174870
+ // Adding a connection or pinning one writes config or your own dossier; a plan with no pin writes nothing.
174871
+ writesLocal: false,
174872
+ writesLocalWhen: (input4) => !input4.plan || (input4.pin?.length ?? 0) > 0,
174873
+ // It asks for tokens: a person on a terminal, or a host's person through the API, never MCP.
174874
+ kind: "cli-only",
174875
+ args: [{ name: "dossier", field: "dossier", description: "A dossier name or file (default: the one the folder matches)", required: false }],
174876
+ options: [
174877
+ { flags: "--cwd <dir>", field: "cwd", description: "The folder to look from (default: the working directory)" },
174878
+ { flags: "--plan", field: "plan", description: "Ask nothing and add no connection; report what each area needs" },
174879
+ { flags: "--pin <area=connection>", field: "pin", description: "The connection your own copy uses where several match (an area, or a section such as environments.prod.github); repeatable" }
174880
+ ],
174881
+ examples: [{}, { dossier: "payments", cwd: ".", plan: true }, { dossier: "payments", pin: ["github=github-work"] }],
174882
+ run: async (input4, ctx) => {
174883
+ const manage = ctx.manage;
174884
+ const catalog = manage.dossiers;
174885
+ if (!catalog) throw new ToilError("NOT_CONFIGURED", "Dossiers are not available here.", { fix: "Run toil dossiers onboard from the CLI." });
174886
+ const applied = chosen(catalog, input4, ctx);
174887
+ const dossier = applied.file.dossier;
174888
+ const ask = input4.plan ? void 0 : manage.prompt;
174889
+ if (!input4.plan && !manage.prompt) {
174890
+ ctx.warn({ code: "ONBOARD_NO_TERMINAL", message: "There is no terminal to ask on, so no connection was added: each area says what it needs. Run toil dossiers onboard in a terminal to add the missing ones." });
174891
+ }
174892
+ const pins = pinsFrom(input4.pin ?? [], areas2, dossier, manage.config);
174893
+ let config5 = manage.config;
174894
+ const reload = () => config5 = reloaded(manage, areas2);
174895
+ const outcomes = [];
174896
+ const toPin = [];
174897
+ for (const target2 of targetsOf(dossier, areas2)) {
174898
+ const outcome2 = match(config5, target2);
174899
+ if (outcome2.status === "missing" && ask) {
174900
+ const created = await offerConnection(ctx, ask, areas2, config5, dossier, target2);
174901
+ if (created) {
174902
+ reload();
174903
+ Object.assign(outcome2, { status: "created", connection: created });
174904
+ delete outcome2.problem;
174905
+ } else if (created === null) {
174906
+ outcome2.problem = { code: "CANCELLED", message: `No ${target2.area.name} connection was added.`, fix: fixFor2(dossier, target2, config5) };
174907
+ }
174908
+ }
174909
+ if (outcome2.status === "ambiguous") {
174910
+ const pick3 = pins.get(target2.path) ?? pins.get(target2.area.name) ?? (ask ? await askPin(ask, dossier, target2, outcome2.candidates) : void 0);
174911
+ if (pick3 !== void 0) {
174912
+ toPin.push({ target: target2, connection: pick3 });
174913
+ Object.assign(outcome2, { status: "pinned", connection: pick3 });
174914
+ delete outcome2.problem;
174915
+ }
174916
+ }
174917
+ if (outcome2.status === "missing") {
174918
+ if (outcome2.problem && !outcome2.problem.fix) outcome2.problem.fix = fixFor2(dossier, target2, config5);
174919
+ outcome2.suggest = suggestionFor(target2, config5);
174920
+ }
174921
+ if (outcome2.status === "ambiguous" && outcome2.problem) outcome2.problem.fix = `Run it in a terminal to choose, or pass --pin ${target2.path}=<one of ${outcome2.candidates.join(", ")}>.`;
174922
+ outcomes.push(outcome2);
174923
+ }
174924
+ for (const [key6] of pins) {
174925
+ if (!toPin.some((p) => p.target.path === key6 || p.target.area.name === key6)) ctx.warn({ code: "ONBOARD_PIN_UNUSED", message: `--pin ${key6}=... wasn't needed: only one of your connections fits it, or none does.` });
174926
+ }
174927
+ const file2 = toPin.length ? pinInOwnCopy(ctx, catalog, manage, areas2, applied.file, toPin) : applied.file;
174928
+ const check2 = checkDossier10(catalog, config5, areas2, file2, input4.cwd);
174929
+ const tested = /* @__PURE__ */ new Map();
174930
+ for (const name3 of [...new Set(outcomes.map((o) => o.connection).filter((n) => n !== null))]) {
174931
+ try {
174932
+ const result = await testConnection(ctx, areas2, config5, name3);
174933
+ tested.set(name3, { ok: true, request: result.request, live: result.live });
174934
+ } catch (err) {
174935
+ const e = toToilError(err);
174936
+ tested.set(name3, { ok: false, error: { code: e.code, message: e.message, ...e.fix ? { fix: e.fix } : {} } });
174937
+ }
174938
+ }
174939
+ const areasOut = outcomes.map((o) => ({ ...o, test: o.connection === null ? null : tested.get(o.connection) }));
174940
+ const ok2 = check2.ok && areasOut.every((a) => a.connection !== null && a.test?.ok === true);
174941
+ if (!ok2) ctx.setExitCode(1);
174942
+ return {
174943
+ dossier: { name: dossier.name, source: applied.file.source, file: forwardSlashes(applied.file.file) },
174944
+ ownCopy: file2 === applied.file ? null : forwardSlashes(file2.file),
174945
+ plan: ask === void 0,
174946
+ ok: ok2,
174947
+ areas: areasOut,
174948
+ check: check2
174949
+ };
174950
+ }
174951
+ });
174952
+ return [onboard];
174953
+ }
174954
+ function targetsOf(dossier, areas2) {
174955
+ const byName4 = new Map(areas2.map((a) => [a.name, a]));
174956
+ const out = [];
174957
+ for (const [name3, section] of Object.entries(dossier.sections)) {
174958
+ const area31 = byName4.get(name3);
174959
+ if (area31) out.push({ area: area31, env: void 0, path: name3, section });
174960
+ }
174961
+ for (const [env, byArea] of Object.entries(dossier.environments)) {
174962
+ for (const [name3, section] of Object.entries(byArea)) {
174963
+ const area31 = byName4.get(name3);
174964
+ if (area31) out.push({ area: area31, env, path: `environments.${env}.${name3}`, section });
174965
+ }
174966
+ }
174967
+ return out;
174968
+ }
174969
+ function match(config5, t) {
174970
+ const base = { area: t.area.name, env: t.env ?? null, path: t.path };
174971
+ const named2 = typeof t.section.connection === "string" ? t.section.connection : void 0;
174972
+ const host = typeof t.section.host === "string" ? t.section.host : void 0;
174973
+ if (named2 !== void 0) {
174974
+ const found = config5.connections[named2]?.area === t.area.name;
174975
+ return {
174976
+ ...base,
174977
+ selects: { connection: named2 },
174978
+ status: found ? "matched" : "missing",
174979
+ connection: found ? named2 : null,
174980
+ ...found ? {} : { problem: { code: "NOT_CONFIGURED", message: `You have no ${t.area.name} connection named ${named2}.` } }
174981
+ };
174982
+ }
174983
+ if (host !== void 0) {
174984
+ const matches2 = connectionsOf(config5, t.area.name).filter((n) => hostMatches(config5.connections[n], host, t.area.siteApis));
174985
+ if (matches2.length === 1) return { ...base, selects: { host }, status: "matched", connection: matches2[0] };
174986
+ if (matches2.length === 0) return { ...base, selects: { host }, status: "missing", connection: null, problem: { code: "NOT_CONFIGURED", message: `You have no ${t.area.name} connection on ${host}.` } };
174987
+ return { ...base, selects: { host }, status: "ambiguous", connection: null, candidates: matches2.sort(), problem: { code: "INVALID_INPUT", message: `${matches2.length} of your ${t.area.name} connections are on ${host}: ${matches2.join(", ")}.` } };
174988
+ }
174989
+ const fallback = defaultConnectionName(config5, t.area.name);
174990
+ if (fallback !== void 0) return { ...base, selects: { default: true }, status: "default", connection: fallback };
174991
+ const all3 = connectionsOf(config5, t.area.name).sort();
174992
+ if (all3.length > 1) return { ...base, selects: { default: true }, status: "ambiguous", connection: null, candidates: all3, problem: { code: "INVALID_INPUT", message: `You have ${all3.length} ${t.area.name} connections and no default: ${all3.join(", ")}.` } };
174993
+ return { ...base, selects: { default: true }, status: "missing", connection: null, problem: { code: "NOT_CONFIGURED", message: `You have no ${t.area.name} connection.` } };
174994
+ }
174995
+ function suggestedBaseUrl(area31, host) {
174996
+ return Object.hasOwn(area31.siteApis ?? {}, host) ? area31.siteApis[host] : `https://${host}`;
174997
+ }
174998
+ function freeName(config5, area31) {
174999
+ if (!config5.connections[area31]) return area31;
175000
+ for (let i = 2; ; i++) if (!config5.connections[`${area31}-${i}`]) return `${area31}-${i}`;
175001
+ }
175002
+ function suggestionFor(t, config5) {
175003
+ const host = typeof t.section.host === "string" ? t.section.host : void 0;
175004
+ return { name: typeof t.section.connection === "string" ? t.section.connection : freeName(config5, t.area.name), ...host ? { baseUrl: suggestedBaseUrl(t.area, host) } : {} };
175005
+ }
175006
+ function fixFor2(dossier, t, config5) {
175007
+ const named2 = typeof t.section.connection === "string" ? t.section.connection : void 0;
175008
+ const host = typeof t.section.host === "string" ? t.section.host : void 0;
175009
+ const name3 = named2 ?? freeName(config5, t.area.name);
175010
+ return `Run toil dossiers onboard ${dossier.name} in a terminal, or toil connections add ${name3} --area ${t.area.name}${host ? ` with a base URL on ${host} (${suggestedBaseUrl(t.area, host)})` : ""}.`;
175011
+ }
175012
+ async function offerConnection(ctx, ask, areas2, config5, dossier, t) {
175013
+ const named2 = typeof t.section.connection === "string" ? t.section.connection : void 0;
175014
+ const host = typeof t.section.host === "string" ? t.section.host : void 0;
175015
+ const where6 = host ? ` on ${host}` : named2 ? ` named ${named2}` : "";
175016
+ const yes = await ask.ask(`Dossier ${dossier.name}'s ${t.path} needs ${withArticle(t.area.name)} connection${where6}, and you have none. Add one now? y/n`, "y", `create:${t.path}`);
175017
+ if (!/^y(es)?$/i.test(yes)) return null;
175018
+ const name3 = named2 ?? await ask.ask(`Name for the new ${t.area.name} connection`, freeName(config5, t.area.name), `name:${t.path}`);
175019
+ try {
175020
+ await addConnection(ctx, areas2, { name: name3, area: t.area.name }, host ? { suggest: { baseUrl: suggestedBaseUrl(t.area, host) }, host } : {});
175021
+ return name3;
175022
+ } catch (err) {
175023
+ const e = toToilError(err);
175024
+ ctx.warn({ code: "ONBOARD_NOT_ADDED", message: `${t.path}: ${e.message}${e.fix ? ` ${e.fix}` : ""}` });
175025
+ return null;
175026
+ }
175027
+ }
175028
+ async function askPin(ask, dossier, t, candidates) {
175029
+ const answer2 = await ask.ask(`Several of your ${t.area.name} connections fit dossier ${dossier.name}'s ${t.path}: ${candidates.join(", ")}. Which should your own copy of it use?`, candidates[0], `pin:${t.path}`);
175030
+ if (candidates.includes(answer2)) return answer2;
175031
+ throw new ToilError("INVALID_INPUT", `"${answer2}" isn't one of ${candidates.join(", ")}. Nothing was pinned.`, { fix: `Run it again and give one of them, or pass --pin ${t.area.name}=<connection>.` });
175032
+ }
175033
+ function pinsFrom(values3, areas2, dossier, config5) {
175034
+ const targets = targetsOf(dossier, areas2);
175035
+ const pins = /* @__PURE__ */ new Map();
175036
+ for (const value2 of values3) {
175037
+ const at10 = value2.indexOf("=");
175038
+ const key6 = value2.slice(0, at10);
175039
+ const name3 = value2.slice(at10 + 1);
175040
+ if (at10 <= 0 || name3 === "") throw new ToilError("INVALID_INPUT", `--pin takes area=connection (or section=connection), and "${value2}" isn't.`, { fix: "For example --pin github=github-work, or --pin environments.prod.github=github-work." });
175041
+ const target2 = targets.find((t) => t.path === key6) ?? targets.find((t) => t.area.name === key6);
175042
+ if (!target2) throw new ToilError("INVALID_INPUT", `Dossier ${dossier.name} has no ${key6} section to pin.`, { fix: `Its sections: ${targets.map((t) => t.path).join(", ") || "none"}.` });
175043
+ const area31 = target2.area.name;
175044
+ if (config5.connections[name3]?.area !== area31) throw new ToilError("INVALID_INPUT", `You have no ${area31} connection named ${name3}.`, { fix: `Run toil connections list --area ${area31} to see yours.` });
175045
+ pins.set(key6, name3);
175046
+ }
175047
+ return pins;
175048
+ }
175049
+ function pinInOwnCopy(ctx, catalog, manage, areas2, from, pins) {
175050
+ const mine = from.source === "user" ? from : catalog.scan().files.find((f) => f.source === "user" && f.dossier?.name === from.dossier.name);
175051
+ const dossier = structuredClone(mine?.dossier ?? from.dossier);
175052
+ for (const { target: target2, connection: connection5 } of pins) {
175053
+ const holder = target2.env === void 0 ? dossier.sections : dossier.environments[target2.env] ??= {};
175054
+ const section = { ...holder[target2.area.name] ?? {} };
175055
+ delete section.host;
175056
+ section.connection = connection5;
175057
+ holder[target2.area.name] = section;
175058
+ }
175059
+ if (manage.via !== "cli") refuseWritesBindings(catalog, manage.config, areas2, dossier, "import");
175060
+ const path2 = mine?.file ?? catalog.userFile(dossier.name);
175061
+ const written = catalog.save(path2, dossier, mine ? "edit" : "create");
175062
+ if (!mine) {
175063
+ ctx.warn({ code: "ONBOARD_OWN_COPY", message: `Your own copy of ${dossier.name}, ${written}, now applies wherever the shared one does. It is yours, so writes may follow its bindings; toil dossiers remove ${dossier.name} takes it away.` });
175064
+ }
175065
+ return catalog.find(written);
175066
+ }
175067
+ function reloaded(manage, areas2) {
175068
+ const path2 = manage.config.files.global;
175069
+ return loadConfig({
175070
+ env: manage.env,
175071
+ cwd: dirname8(path2),
175072
+ home: dirname8(dirname8(path2)),
175073
+ configPath: path2,
175074
+ areas: areas2.map((a) => ({ name: a.name, fallbacks: a.fallbacks, contextInputs: Object.keys(a.context), ...a.siteApis ? { siteApis: a.siteApis } : {} }))
175075
+ });
175076
+ }
175077
+
174503
175078
  // src/feedback/command.ts
174504
175079
  init_errors();
174505
175080
 
@@ -174728,14 +175303,14 @@ function reposCommands() {
174728
175303
 
174729
175304
  // src/setup/commands.ts
174730
175305
  import { homedir as homedir2 } from "node:os";
174731
- import { dirname as dirname9, join as join16 } from "node:path";
175306
+ import { dirname as dirname10, join as join16 } from "node:path";
174732
175307
  import { fileURLToPath as fileURLToPath2 } from "node:url";
174733
175308
  init_errors();
174734
175309
 
174735
175310
  // src/core/shell-profile.ts
174736
175311
  init_errors();
174737
175312
  import { mkdirSync as mkdirSync8, realpathSync as realpathSync8, writeFileSync as writeFileSync6 } from "node:fs";
174738
- import { basename as basename11, dirname as dirname8, join as join15 } from "node:path";
175313
+ import { basename as basename11, dirname as dirname9, join as join15 } from "node:path";
174739
175314
  var SHELLS = ["bash", "zsh", "powershell"];
174740
175315
  var BEGIN = "# >>> toil alias >>>";
174741
175316
  var END = "# <<< toil alias <<<";
@@ -174811,7 +175386,7 @@ function editProfile(o, change2) {
174811
175386
  if (after === before2) return { path: path2, text: after, written: false };
174812
175387
  try {
174813
175388
  const target2 = exists2 ? realpathSync8(path2) : path2;
174814
- mkdirSync8(dirname8(target2), { recursive: true });
175389
+ mkdirSync8(dirname9(target2), { recursive: true });
174815
175390
  writeFileSync6(target2, after, "utf8");
174816
175391
  } catch (err) {
174817
175392
  throw new ToilError("INVALID_INPUT", `toil couldn't write ${forwardSlashes(path2)}: ${err.message}`, {
@@ -174835,7 +175410,7 @@ function nodeSetupHost() {
174835
175410
  cwd: process.cwd(),
174836
175411
  env: { SHELL: process.env.SHELL, ZDOTDIR: process.env.ZDOTDIR },
174837
175412
  // In the bundle this module is dist/toil-lib.js; the alias runs the bin beside it, dist/toil.js.
174838
- bundle: join16(dirname9(fileURLToPath2(import.meta.url)), "toil.js")
175413
+ bundle: join16(dirname10(fileURLToPath2(import.meta.url)), "toil.js")
174839
175414
  };
174840
175415
  }
174841
175416
  function setupCommands(host = nodeSetupHost) {
@@ -174963,7 +175538,7 @@ function skillsConfigCommands() {
174963
175538
  const dir = input4.localPath ? isAbsolute11(input4.localPath) ? resolve9(input4.localPath) : ctx.files.resolve(input4.localPath) : clonePathOf({ name: name3, repoUrl: input4.url, localPath: before2?.localPath }, roots.home);
174964
175539
  checkClonePath(dir, roots.home, path2);
174965
175540
  let token = "";
174966
- if (url2 && prompt) token = await prompt.askSecret(`Access token for ${url2.host} (leave empty for a public repository)`);
175541
+ if (url2 && prompt) token = await askCheckedSecret(prompt, `Access token for ${url2.host} (leave empty for a public repository)`, "token", { empty: existing?.token ? "keep" : "skip" });
174967
175542
  if (url2 && !prompt && !existing?.token) {
174968
175543
  ctx.warn({
174969
175544
  code: "SKILLS_NO_TOKEN",
@@ -175158,8 +175733,8 @@ function skillsConfigCommands() {
175158
175733
  const meta3 = readMeta(f.dir);
175159
175734
  const push = (skill, record3, enabled) => {
175160
175735
  const recorded = record3?.marketplace ?? null;
175161
- const match = registered.find(([n, c]) => recorded !== null && n === recorded || record3?.installedFrom !== void 0 && c.repoUrl === record3.installedFrom);
175162
- const clone2 = match ? clonePathOf(asMarketplace(match[0], match[1]), roots.home) : void 0;
175736
+ const match2 = registered.find(([n, c]) => recorded !== null && n === recorded || record3?.installedFrom !== void 0 && c.repoUrl === record3.installedFrom);
175737
+ const clone2 = match2 ? clonePathOf(asMarketplace(match2[0], match2[1]), roots.home) : void 0;
175163
175738
  const version3 = typeof record3?.toilVersion === "string" ? record3.toilVersion : null;
175164
175739
  skills.push({
175165
175740
  skill,
@@ -175170,8 +175745,8 @@ function skillsConfigCommands() {
175170
175745
  enabled,
175171
175746
  source: record3?.source ?? "untracked",
175172
175747
  plugin: record3?.plugin ?? null,
175173
- marketplace: recorded ?? match?.[0] ?? null,
175174
- repoUrl: (match ? String(match[1].repoUrl) : void 0) ?? record3?.installedFrom ?? null,
175748
+ marketplace: recorded ?? match2?.[0] ?? null,
175749
+ repoUrl: (match2 ? String(match2[1].repoUrl) : void 0) ?? record3?.installedFrom ?? null,
175175
175750
  localPath: clone2 ? slashes2(clone2) : null,
175176
175751
  upstreamRemote: clone2 ? originOf(clone2) : null,
175177
175752
  branch: record3?.branch ?? null,
@@ -175339,7 +175914,7 @@ function skillCommands(areas2) {
175339
175914
 
175340
175915
  // src/registry.ts
175341
175916
  var areas = modules.flatMap((m2) => m2.area ? [m2.area] : []);
175342
- var commands33 = withCoreAliases([...modules.flatMap((m2) => m2.commands), ...connectionsCommands(areas), ...dossiersCommands(areas), ...dossierBuildCommands(areas), ...reposCommands(), ...skillsConfigCommands(), ...skillCommands(areas), ...setupCommands(), ...auditCommands(() => commands33), ...feedbackCommands(), waitCommand], areas);
175917
+ var commands33 = withCoreAliases([...modules.flatMap((m2) => m2.commands), ...connectionsCommands(areas), ...dossiersCommands(areas), ...dossierBuildCommands(areas), ...dossierOnboardCommands(areas), ...reposCommands(), ...skillsConfigCommands(), ...skillCommands(areas), ...setupCommands(), ...auditCommands(() => commands33), ...feedbackCommands(), waitCommand], areas);
175343
175918
  assertUniquePaths(commands33);
175344
175919
  var ROUTED_ALIASES = [
175345
175920
  {
@@ -175354,7 +175929,7 @@ var ROUTED_ALIASES = [
175354
175929
  var routedAliases = resolveRoutedAliases(ROUTED_ALIASES, commands33);
175355
175930
 
175356
175931
  // src/welcome/data.ts
175357
- import { existsSync as existsSync11 } from "node:fs";
175932
+ import { existsSync as existsSync12 } from "node:fs";
175358
175933
  import { join as join19 } from "node:path";
175359
175934
  init_errors();
175360
175935
  function gatherWelcomeData(o) {
@@ -175371,7 +175946,7 @@ function gatherWelcomeData(o) {
175371
175946
  node: process.versions.node,
175372
175947
  platform: `${process.platform} ${process.arch}`,
175373
175948
  configPath,
175374
- configExists: existsSync11(configPath),
175949
+ configExists: existsSync12(configPath),
175375
175950
  config: config5,
175376
175951
  areas: o.catalog,
175377
175952
  mcpAreas: o.mcpAreas,
@@ -177023,7 +177598,7 @@ var heading = (caps, text4) => paint(caps, PALETTE.amber, text4);
177023
177598
  var muted = (caps, text4) => paint(caps, PALETTE.muted, text4);
177024
177599
  var faint = (caps, text4) => paint(caps, PALETTE.faint, text4);
177025
177600
  var ok = (caps, good, text4) => paint(caps, good ? PALETTE.amber : PALETTE.accent, text4);
177026
- function hostOf3(value2) {
177601
+ function hostOf2(value2) {
177027
177602
  if (typeof value2 !== "string") return "";
177028
177603
  try {
177029
177604
  return new URL(value2).host;
@@ -177119,7 +177694,7 @@ function connectionsScreen(caps, data, session5 = { health: {} }) {
177119
177694
  return [
177120
177695
  name3 + (isDefault && connectionsOf(config5, c.area).length > 1 ? " *" : ""),
177121
177696
  c.area,
177122
- hostOf3(c.baseUrl) || hostOf3(c.host) || faint(caps, "-"),
177697
+ hostOf2(c.baseUrl) || hostOf2(c.host) || faint(caps, "-"),
177123
177698
  connectionWrites(c) ? ok(caps, false, "writes on") : muted(caps, "read only"),
177124
177699
  fromEnv2 ? muted(caps, "env ") : muted(caps, "file"),
177125
177700
  healthWord(caps, session5.health[name3])
@@ -177240,7 +177815,7 @@ var connectionsList = {
177240
177815
  return [
177241
177816
  ...names2.map((name3) => ({
177242
177817
  label: name3,
177243
- hint: cfg ? `${cfg.connections[name3].area} ${hostOf3(cfg.connections[name3].baseUrl) || hostOf3(cfg.connections[name3].host)}`.trim() : "",
177818
+ hint: cfg ? `${cfg.connections[name3].area} ${hostOf2(cfg.connections[name3].baseUrl) || hostOf2(cfg.connections[name3].host)}`.trim() : "",
177244
177819
  action: { go: "connection", params: { name: name3 } }
177245
177820
  })),
177246
177821
  { label: "Add a connection", hint: "Pick a service, sign in, test it", action: { go: "add-area" } },
@@ -177262,7 +177837,7 @@ var connectionView = {
177262
177837
  paint(caps, PALETTE.amber, name3),
177263
177838
  "",
177264
177839
  `${paint(caps, PALETTE.muted, "Area ")} ${conn.area}${isDefault ? paint(caps, PALETTE.faint, " (its default)") : ""}`,
177265
- `${paint(caps, PALETTE.muted, "Host ")} ${hostOf3(conn.baseUrl) || hostOf3(conn.host) || "-"}`,
177840
+ `${paint(caps, PALETTE.muted, "Host ")} ${hostOf2(conn.baseUrl) || hostOf2(conn.host) || "-"}`,
177266
177841
  `${paint(caps, PALETTE.muted, "Writes ")} ${connectionWrites(conn) ? ok(caps, false, "on") : "off (read only)"}`,
177267
177842
  `${paint(caps, PALETTE.muted, "Health ")} ${healthWord(caps, health)}${area31 && !area31.live ? paint(caps, PALETTE.faint, " (no live check for this area; the test checks settings and secret)") : ""}`
177268
177843
  ];
@@ -177396,7 +177971,7 @@ var muted2 = (caps, text4) => paint(caps, PALETTE.muted, text4);
177396
177971
  var faint2 = (caps, text4) => paint(caps, PALETTE.faint, text4);
177397
177972
  var heading2 = (caps, text4) => paint(caps, PALETTE.amber, text4);
177398
177973
  var label2 = (caps, text4) => muted2(caps, text4.padEnd(10));
177399
- var plural2 = (n, word2) => `${n} ${n === 1 ? word2 : word2.endsWith("y") ? `${word2.slice(0, -1)}ies` : `${word2}s`}`;
177974
+ var plural3 = (n, word2) => `${n} ${n === 1 ? word2 : word2.endsWith("y") ? `${word2.slice(0, -1)}ies` : `${word2}s`}`;
177400
177975
  var refOf = (p) => p.frame.params.ref;
177401
177976
  var shownOf = (p, ref2 = refOf(p)) => p.session.dossiers?.[ref2]?.show;
177402
177977
  var checkedOf = (p, ref2 = refOf(p)) => p.session.dossiers?.[ref2]?.check;
@@ -177450,13 +178025,14 @@ function change(params2, title, steps, then) {
177450
178025
  if (params2.flow === "edit") return { go: "dossier-save", params: { ref: ref2, title, steps: json2(steps.map((s) => s.args)), then: json2(then), ...params2.area ? { area: params2.area } : {}, ...params2.env ? { env: params2.env } : {} } };
177451
178026
  return { run: editRun(title, ref2, steps, then, params2.flow === "fix") };
177452
178027
  }
177453
- function onHost(settings, host) {
177454
- return settings !== void 0 && hostMatches(settings, host.trim());
178028
+ function onHost(settings, host, siteApis) {
178029
+ return settings !== void 0 && hostMatches(settings, host.trim(), siteApis);
177455
178030
  }
178031
+ var siteApisOf = (data, area31) => data.areas.find((a) => a.name === area31)?.siteApis;
177456
178032
  function writesTargets(data, area31, pick3) {
177457
178033
  const cfg = config3(data);
177458
178034
  if (!cfg) return [];
177459
- const names2 = pick3.connection !== void 0 ? [pick3.connection] : connectionsOf(cfg, area31).filter((name3) => onHost(cfg.connections[name3], pick3.host ?? ""));
178035
+ const names2 = pick3.connection !== void 0 ? [pick3.connection] : connectionsOf(cfg, area31).filter((name3) => onHost(cfg.connections[name3], pick3.host ?? "", siteApisOf(data, area31)));
177460
178036
  return names2.filter((name3) => cfg.connections[name3]?.area === area31 && connectionWrites(cfg.connections[name3]));
177461
178037
  }
177462
178038
  function bind2(p, flags, title, pick3) {
@@ -177522,6 +178098,7 @@ var openRun = (ref2, root) => ({
177522
178098
  steps: [showStep(ref2)],
177523
178099
  next: (r) => r[0]?.envelope.ok ? { go: "dossier", params: { ref: ref2 }, ...root ? { root } : {} } : void 0
177524
178100
  });
178101
+ var onboardRun = { title: "Set up this repo", steps: [{ args: ["dossiers", "onboard"], label: "Match each area to your connections; add the ones you lack" }], showData: true };
177525
178102
  var dossiersView = {
177526
178103
  title: () => "Dossiers",
177527
178104
  body: (caps, p) => [
@@ -177529,11 +178106,12 @@ var dossiersView = {
177529
178106
  "",
177530
178107
  `${label2(caps, "Folder")} ${p.data.folder.repo ? p.data.folder.repo.root : p.data.folder.cwd}${p.data.folder.repo ? "" : faint2(caps, " (not in a git repository)")}`
177531
178108
  ],
177532
- items: () => [
178109
+ items: (p) => [
177533
178110
  { label: "This folder", hint: "Which dossier applies here, and why", action: { run: contextRun } },
177534
178111
  { label: "Your dossiers", hint: "Every dossier toil can see; open one to review or edit it", action: { run: listRun() } },
177535
178112
  { label: "Create a dossier", hint: "Name, repos, areas, environments, then a review", action: { go: "dossier-new" } },
177536
178113
  { label: "Import a dossier", hint: "Adopt a shared dossier file as your own", action: { go: "dossier-import" } },
178114
+ ...p.data.folder.repo ? [{ label: "Set up this repo", hint: "Connect its dossier's areas to your connections, adding any you lack", action: { run: onboardRun } }] : [],
177537
178115
  { label: "Hand off to an agent", hint: "A prompt and the MCP areas to build one with an agent", action: { go: "dossier-agent" } }
177538
178116
  ]
177539
178117
  };
@@ -177565,7 +178143,12 @@ var folderView = {
177565
178143
  items: (p) => {
177566
178144
  const c = parse5(p.frame.params.context, void 0);
177567
178145
  if (!c) return [];
177568
- if (c.dossier) return [{ label: `Open ${c.dossier.name}`, hint: "Review, edit or export it", action: { run: openRun(c.dossier.name) } }];
178146
+ if (c.dossier) {
178147
+ return [
178148
+ { label: `Open ${c.dossier.name}`, hint: "Review, edit or export it", action: { run: openRun(c.dossier.name) } },
178149
+ { label: "Set up this repo", hint: `Connect ${c.dossier.name}'s areas to your connections, adding any you lack`, action: { run: onboardRun } }
178150
+ ];
178151
+ }
177569
178152
  if (c.candidates.length > 1) return c.candidates.map((x) => ({ label: `Open ${x.name}`, hint: x.file, action: { run: openRun(x.name) } }));
177570
178153
  if (!c.repo) return [{ label: "Create a dossier", hint: "Name, repos, areas, environments", action: { go: "dossier-new" } }];
177571
178154
  return [
@@ -177591,7 +178174,7 @@ var listView = {
177591
178174
  const list7 = parse5(p.frame.params.list, { dossiers: [], broken: [] });
177592
178175
  return list7.dossiers.map((d2) => {
177593
178176
  const ref2 = d2.shadowedBy ? d2.file : d2.name;
177594
- const hint = `${d2.source}${d2.description ? `, ${d2.description}` : ""}${d2.shadowedBy ? `, overridden by ${d2.shadowedBy}` : ""}${d2.problems ? `, ${plural2(d2.problems, "problem")}` : ""}`;
178177
+ const hint = `${d2.source}${d2.description ? `, ${d2.description}` : ""}${d2.shadowedBy ? `, overridden by ${d2.shadowedBy}` : ""}${d2.problems ? `, ${plural3(d2.problems, "problem")}` : ""}`;
177595
178178
  if (p.frame.params.mode === "add-repo") {
177596
178179
  const repo = p.frame.params.repo;
177597
178180
  return { label: d2.name, hint, action: { run: { title: `Add ${repo} to ${d2.name}`, steps: [{ args: ["dossiers", "add-repo", ref2, repo] }, showStep(ref2)], next: (r) => r.every((x) => x.envelope.ok) ? { go: "dossier", params: { ref: ref2 } } : void 0 } } };
@@ -177627,7 +178210,7 @@ var dossierView = {
177627
178210
  lines.push(` ${area31.padEnd(12)} ${conn} ${writes}${a.env ? faint2(caps, ` env ${a.env}`) : ""}${inputs ? faint2(caps, ` ${inputs}`) : ""}`);
177628
178211
  if (a.error) lines.push(` ${ok(caps, false, `${a.error.code}: ${a.error.message}`)}`);
177629
178212
  }
177630
- if (s.problems.length) lines.push("", ok(caps, false, `${plural2(s.problems.length, "problem")} reading it; Review lists them with their fixes.`));
178213
+ if (s.problems.length) lines.push("", ok(caps, false, `${plural3(s.problems.length, "problem")} reading it; Review lists them with their fixes.`));
177631
178214
  return lines;
177632
178215
  },
177633
178216
  items: (p) => {
@@ -177671,7 +178254,7 @@ var reviewView = {
177671
178254
  const s = shownOf(p);
177672
178255
  if (!c) return [muted2(caps, "Not checked yet.")];
177673
178256
  const errors = c.problems.filter((x) => x.level === "error").length;
177674
- const lines = [c.ok ? ok(caps, true, `No errors${c.problems.length ? `; ${plural2(c.problems.length, "warning")}` : ""}. Checked locally: no service was contacted.`) : ok(caps, false, `${plural2(errors, "error")}${c.message ? `: ${c.message}` : ""}`)];
178257
+ const lines = [c.ok ? ok(caps, true, `No errors${c.problems.length ? `; ${plural3(c.problems.length, "warning")}` : ""}. Checked locally: no service was contacted.`) : ok(caps, false, `${plural3(errors, "error")}${c.message ? `: ${c.message}` : ""}`)];
177675
178258
  for (const g of groupFindings(c.problems)) {
177676
178259
  lines.push("", heading2(caps, g.title));
177677
178260
  for (const x of g.problems) lines.push(` ${x.level === "error" ? ok(caps, false, x.code) : muted2(caps, x.code)} ${faint2(caps, x.path || "(file)")}`, muted2(caps, ` ${x.message}`));
@@ -177733,7 +178316,7 @@ var serviceView = {
177733
178316
  const r = parse5(p.frame.params.result, void 0);
177734
178317
  if (!r) return [];
177735
178318
  const missing3 = r.checks.filter((c) => !c.found);
177736
- const lines = [r.ok ? ok(caps, true, `All ${plural2(r.checked, "value")} found on ${r.connection ?? "the connection"}.`) : ok(caps, false, `${missing3.length} of ${r.checked} not found on ${r.connection ?? "the connection"}.`), ""];
178319
+ const lines = [r.ok ? ok(caps, true, `All ${plural3(r.checked, "value")} found on ${r.connection ?? "the connection"}.`) : ok(caps, false, `${missing3.length} of ${r.checked} not found on ${r.connection ?? "the connection"}.`), ""];
177737
178320
  for (const c of r.checks) lines.push(` ${c.found ? ok(caps, true, "found ") : ok(caps, false, "missing")} ${c.kind} ${c.value} ${faint2(caps, c.path)}`);
177738
178321
  if (missing3.length) lines.push("", muted2(caps, "Change a value below, or relink the area if it points at the wrong instance."));
177739
178322
  return lines;
@@ -177758,7 +178341,7 @@ var editView = {
177758
178341
  const s = shownOf(p);
177759
178342
  const flow = { ref: ref2, flow: "edit" };
177760
178343
  return [
177761
- { label: "Repos", hint: `${plural2(reposOf(s).length, "repo")}; add from a scan or by remote`, action: { go: "dossier-repos-edit", params: { ref: ref2 } } },
178344
+ { label: "Repos", hint: `${plural3(reposOf(s).length, "repo")}; add from a scan or by remote`, action: { go: "dossier-repos-edit", params: { ref: ref2 } } },
177762
178345
  ...sectionsOf(s).map((x) => ({ label: where5(x.area, x.env), hint: typeof x.section.connection === "string" ? `connection ${x.section.connection}` : typeof x.section.host === "string" ? `host ${x.section.host}` : "your default connection", action: { go: "dossier-area", params: { ref: ref2, area: x.area, ...x.env ? { env: x.env } : {} } } })),
177763
178346
  { label: "Link an area", hint: "Jira, Confluence, Sonar, ...", action: { go: "dossier-area-pick", params: { ...flow, then: backTo("dossier-edit") } } },
177764
178347
  { label: "Add an environment", hint: "Its resources per area, e.g. an OpenShift namespace", action: { go: "dossier-env-name", params: { ...flow, then: backTo("dossier-edit") } } }
@@ -177817,7 +178400,7 @@ var areaPickView = {
177817
178400
  const linked = new Set(sectionsOf(shownOf(p)).filter((x) => x.env === p.frame.params.env).map((x) => x.area));
177818
178401
  const count4 = (area31) => cfg ? connectionsOf(cfg, area31).length : 0;
177819
178402
  const areas2 = p.data.areas.filter((a) => a.configurable && !linked.has(a.name) && a.name !== "skills").sort((a, b) => Number(count4(b.name) > 0) - Number(count4(a.name) > 0) || a.name.localeCompare(b.name));
177820
- return areas2.map((a) => ({ label: a.name, hint: count4(a.name) ? `${plural2(count4(a.name), "connection")}; ${a.description}` : a.description, action: { go: "dossier-connection", params: { ...p.frame.params, area: a.name } } }));
178403
+ return areas2.map((a) => ({ label: a.name, hint: count4(a.name) ? `${plural3(count4(a.name), "connection")}; ${a.description}` : a.description, action: { go: "dossier-connection", params: { ...p.frame.params, area: a.name } } }));
177821
178404
  }
177822
178405
  };
177823
178406
  var connectionView2 = {
@@ -177839,7 +178422,7 @@ var connectionView2 = {
177839
178422
  const items = names2.map((name3) => {
177840
178423
  const conn = cfg.connections[name3];
177841
178424
  const writes = connectionWrites(conn);
177842
- const hint = [hostOf3(conn.baseUrl) || hostOf3(conn.host), writes ? "writes on: asks you to confirm" : "read only", name3 === dflt ? "your default" : "", section.connection === name3 ? "selected now" : ""].filter(Boolean).join(", ");
178425
+ const hint = [hostOf2(conn.baseUrl) || hostOf2(conn.host), writes ? "writes on: asks you to confirm" : "read only", name3 === dflt ? "your default" : "", section.connection === name3 ? "selected now" : ""].filter(Boolean).join(", ");
177843
178426
  return { label: name3, hint, action: bind2(p, ["--connection", name3], `Link ${where5(area31, env)} to ${name3}`, { connection: name3 }) };
177844
178427
  });
177845
178428
  items.push({ label: "By host", hint: "For a dossier you will share", action: { go: "dossier-host", params: p.frame.params } });
@@ -177859,7 +178442,7 @@ var hostView = {
177859
178442
  title: () => "Host",
177860
178443
  body: (caps, p) => {
177861
178444
  const cfg = config3(p.data);
177862
- const hosts = cfg ? [...new Set(connectionsOf(cfg, p.frame.params.area).map((n) => hostOf3(cfg.connections[n].baseUrl) || hostOf3(cfg.connections[n].host)).filter(Boolean))] : [];
178445
+ const hosts = cfg ? [...new Set(connectionsOf(cfg, p.frame.params.area).map((n) => hostOf2(cfg.connections[n].baseUrl) || hostOf2(cfg.connections[n].host)).filter(Boolean))] : [];
177863
178446
  return [muted2(caps, "The host your connection to it has, e.g. jira.imagile.dev, with :port only when it matters."), ...hosts.length ? ["", faint2(caps, `Yours: ${hosts.join(", ")}`)] : []];
177864
178447
  },
177865
178448
  input: {
@@ -177997,7 +178580,7 @@ var discoverView = {
177997
178580
  if (added.length === 0) return thenOf(params2);
177998
178581
  const found = parse5(params2.found, []);
177999
178582
  const steps = d2.key ? [{ args: sectionArgs(params2, added.flatMap((id9) => ["--add", `${d2.key}=${id9}`])) }] : added.map((id9) => ({ args: ["dossiers", "field", params2.ref, params2.area, aliasFor(found.find((x) => x.id === id9)?.name ?? id9, id9), id9] }));
178000
- return change(params2, `Add ${plural2(added.length, d2.key ? d2.what.replace(/s$/, "") : "field")} to ${params2.area}`, steps, thenOf(params2));
178583
+ return change(params2, `Add ${plural3(added.length, d2.key ? d2.what.replace(/s$/, "") : "field")} to ${params2.area}`, steps, thenOf(params2));
178001
178584
  }
178002
178585
  }
178003
178586
  };
@@ -178024,7 +178607,7 @@ var saveView = {
178024
178607
  items: (p) => {
178025
178608
  const steps = parse5(p.frame.params.steps, []).map((args) => ({ args }));
178026
178609
  return [
178027
- { label: "Save", hint: plural2(steps.length, "command"), action: { run: editRun(p.frame.params.title ?? "Save", refOf(p), steps, thenOf(p.frame.params)) } },
178610
+ { label: "Save", hint: plural3(steps.length, "command"), action: { run: editRun(p.frame.params.title ?? "Save", refOf(p), steps, thenOf(p.frame.params)) } },
178028
178611
  { label: "Back", hint: "Change it first", action: { back: true } }
178029
178612
  ];
178030
178613
  }
@@ -178058,7 +178641,7 @@ var reposChecklist = {
178058
178641
  const repos = parse5(p.frame.params.repos, []);
178059
178642
  return [
178060
178643
  ...p.frame.params.flow === "create" ? [heading2(caps, step3(2, "repositories")), ""] : [],
178061
- repos.length ? muted2(caps, `${plural2(repos.length, "repository")} found. Tick the ones in this dossier; enter adds them.`) : muted2(caps, "None found there. Enter goes on.")
178644
+ repos.length ? muted2(caps, `${plural3(repos.length, "repository")} found. Tick the ones in this dossier; enter adds them.`) : muted2(caps, "None found there. Enter goes on.")
178062
178645
  ];
178063
178646
  },
178064
178647
  checklist: {
@@ -178073,7 +178656,7 @@ var reposChecklist = {
178073
178656
  const have = new Set(reposOf(shownOf(p)).map((r) => r.path));
178074
178657
  const added = checked2.filter((path2) => !have.has(path2));
178075
178658
  if (added.length === 0) return thenOf(params2);
178076
- return change(params2, `Add ${plural2(added.length, "repo")}`, added.map((path2) => ({ args: ["dossiers", "add-repo", params2.ref, path2] })), thenOf(params2));
178659
+ return change(params2, `Add ${plural3(added.length, "repo")}`, added.map((path2) => ({ args: ["dossiers", "add-repo", params2.ref, path2] })), thenOf(params2));
178077
178660
  }
178078
178661
  }
178079
178662
  };
@@ -178130,7 +178713,7 @@ var newAreasView = {
178130
178713
  const yours = p.data.areas.filter((a) => a.configurable && a.name !== "skills" && !linked.has(a.name) && cfg && connectionsOf(cfg, a.name).length > 0);
178131
178714
  const params2 = { ref: ref2, flow: "create", discover: "1", then: backTo("dossier-new-areas") };
178132
178715
  return [
178133
- ...yours.map((a) => ({ label: a.name, hint: `${plural2(connectionsOf(cfg, a.name).length, "connection")}${DISCOVERY[a.name] ? `; discovers ${DISCOVERY[a.name].what}` : ""}`, action: { go: "dossier-connection", params: { ...params2, area: a.name } } })),
178716
+ ...yours.map((a) => ({ label: a.name, hint: `${plural3(connectionsOf(cfg, a.name).length, "connection")}${DISCOVERY[a.name] ? `; discovers ${DISCOVERY[a.name].what}` : ""}`, action: { go: "dossier-connection", params: { ...params2, area: a.name } } })),
178134
178717
  { label: "Another area", hint: "One you have no connection for yet", action: { go: "dossier-area-pick", params: params2 } },
178135
178718
  { label: "Next: environments", hint: "Step 5", action: { go: "dossier-new-envs", params: { ref: ref2, flow: "create" } } }
178136
178719
  ];
@@ -178283,7 +178866,7 @@ function stillToSetUp(data, result) {
178283
178866
  return result.toSetUp.filter((x) => {
178284
178867
  if (!cfg) return true;
178285
178868
  if (x.connection) return cfg.connections[x.connection]?.area !== x.area;
178286
- return x.host !== void 0 && !connectionsOf(cfg, x.area).some((name3) => onHost(cfg.connections[name3], x.host));
178869
+ return x.host !== void 0 && !connectionsOf(cfg, x.area).some((name3) => onHost(cfg.connections[name3], x.host, siteApisOf(data, x.area)));
178287
178870
  });
178288
178871
  }
178289
178872
  var importDoneView = {
@@ -178294,7 +178877,7 @@ var importDoneView = {
178294
178877
  return [
178295
178878
  ...r.imported.map((x) => ok(caps, true, `${x.name} is yours now: ${x.file}`)),
178296
178879
  "",
178297
- left.length ? heading2(caps, `${plural2(left.length, "connection")} to set up`) : ok(caps, true, "Every connection it names is one you have."),
178880
+ left.length ? heading2(caps, `${plural3(left.length, "connection")} to set up`) : ok(caps, true, "Every connection it names is one you have."),
178298
178881
  ...left.map((x) => muted2(caps, ` ${x.problem}`))
178299
178882
  ];
178300
178883
  },
@@ -178369,15 +178952,15 @@ function dossiersOutcome(result) {
178369
178952
  const said = (text4, good = true) => ({ good, text: text4 });
178370
178953
  if (group === "repos" && verb === "scan") {
178371
178954
  const n = Array.isArray(d2.repos) ? d2.repos.length : 0;
178372
- return said(`Found ${plural2(n, "repository")} under ${String(d2.folder ?? "the folder")}${d2.truncated ? " (stopped early: there were too many folders)" : ""}.`);
178955
+ return said(`Found ${plural3(n, "repository")} under ${String(d2.folder ?? "the folder")}${d2.truncated ? " (stopped early: there were too many folders)" : ""}.`);
178373
178956
  }
178374
178957
  if (verb === "check-dossier") {
178375
178958
  const checks = Array.isArray(d2.checks) ? d2.checks : [];
178376
178959
  const missing3 = checks.filter((c) => !c.found).length;
178377
- return said(missing3 ? `${missing3} of ${checks.length} not found on ${String(d2.connection ?? "the connection")}.` : `All ${plural2(checks.length, "value")} found on ${String(d2.connection ?? "the connection")}.`, missing3 === 0);
178960
+ return said(missing3 ? `${missing3} of ${checks.length} not found on ${String(d2.connection ?? "the connection")}.` : `All ${plural3(checks.length, "value")} found on ${String(d2.connection ?? "the connection")}.`, missing3 === 0);
178378
178961
  }
178379
178962
  const discovery = Object.values(DISCOVERY).find((x) => x.args.every((a, i) => result.args[i] === a));
178380
- if (discovery) return said(`Found ${plural2(discovered(result, discovery).length, discovery.what.replace(/s$/, ""))}.`);
178963
+ if (discovery) return said(`Found ${plural3(discovered(result, discovery).length, discovery.what.replace(/s$/, ""))}.`);
178381
178964
  if (group !== "dossiers") return void 0;
178382
178965
  const unchanged = d2.changed === false ? " (it already was)" : "";
178383
178966
  switch (verb) {
@@ -178388,18 +178971,18 @@ function dossiersOutcome(result) {
178388
178971
  }
178389
178972
  case "list": {
178390
178973
  const l = d2;
178391
- return said(`${plural2(l.dossiers.length, "dossier")}${l.broken.length ? `, ${l.broken.length} broken` : ""}.`, l.broken.length === 0);
178974
+ return said(`${plural3(l.dossiers.length, "dossier")}${l.broken.length ? `, ${l.broken.length} broken` : ""}.`, l.broken.length === 0);
178392
178975
  }
178393
178976
  case "show": {
178394
178977
  const s = d2;
178395
178978
  const areas2 = Object.keys(s.areas ?? {});
178396
- return said(`${s.name}: ${plural2(reposOf(s).length, "repo")}, ${areas2.length ? areas2.join(", ") : "no areas yet"}.`);
178979
+ return said(`${s.name}: ${plural3(reposOf(s).length, "repo")}, ${areas2.length ? areas2.join(", ") : "no areas yet"}.`);
178397
178980
  }
178398
178981
  case "check": {
178399
178982
  const c = d2;
178400
178983
  const errors = c.problems.filter((x) => x.level === "error").length;
178401
178984
  const warnings2 = c.problems.length - errors;
178402
- return said(c.ok ? `${c.name} checks out${warnings2 ? `, with ${plural2(warnings2, "warning")}` : ""}.` : `${c.name ?? "It"} has ${plural2(errors, "error")}${warnings2 ? ` and ${plural2(warnings2, "warning")}` : ""}.`, c.ok);
178985
+ return said(c.ok ? `${c.name} checks out${warnings2 ? `, with ${plural3(warnings2, "warning")}` : ""}.` : `${c.name ?? "It"} has ${plural3(errors, "error")}${warnings2 ? ` and ${plural3(warnings2, "warning")}` : ""}.`, c.ok);
178403
178986
  }
178404
178987
  case "init":
178405
178988
  return said(`Created ${String(d2.name)} in ${String(d2.file)}.`);
@@ -178411,10 +178994,10 @@ function dossiersOutcome(result) {
178411
178994
  case "field":
178412
178995
  return said(`Saved the ${String(d2.area)} field names in ${String(d2.name)}${unchanged}.`);
178413
178996
  case "export":
178414
- return said(`Wrote ${String(d2.file)}${Array.isArray(d2.hosts) && d2.hosts.length ? `, with ${plural2(d2.hosts.length, "connection")} shared as a host` : ""}${d2.droppedPaths ? `; ${plural2(Number(d2.droppedPaths), "local path")} left out` : ""}.`);
178997
+ return said(`Wrote ${String(d2.file)}${Array.isArray(d2.hosts) && d2.hosts.length ? `, with ${plural3(d2.hosts.length, "connection")} shared as a host` : ""}${d2.droppedPaths ? `; ${plural3(Number(d2.droppedPaths), "local path")} left out` : ""}.`);
178415
178998
  case "import": {
178416
178999
  const r = d2;
178417
- return said(`Imported ${r.imported.map((x) => x.name).join(", ") || "nothing"}${r.toSetUp.length ? `; ${plural2(r.toSetUp.length, "connection")} to set up` : ""}.`, !r.failed?.length);
179000
+ return said(`Imported ${r.imported.map((x) => x.name).join(", ") || "nothing"}${r.toSetUp.length ? `; ${plural3(r.toSetUp.length, "connection")} to set up` : ""}.`, !r.failed?.length);
178418
179001
  }
178419
179002
  case "unlink":
178420
179003
  return said(`Removed ${d2.env ? `${String(d2.env)}: ` : ""}${String(d2.area)} from ${String(d2.name)}${Array.isArray(d2.credentialsRemoved) ? ", and the credential from its stored remotes" : ""}.`);
@@ -179549,9 +180132,9 @@ function pause(ms, onKey) {
179549
180132
 
179550
180133
  // src/welcome/rogue/save.ts
179551
180134
  import { createCipheriv, createDecipheriv, randomBytes, scryptSync as scryptSync2 } from "node:crypto";
179552
- import { existsSync as existsSync12, readFileSync as readFileSync9 } from "node:fs";
180135
+ import { existsSync as existsSync13, readFileSync as readFileSync9 } from "node:fs";
179553
180136
  var SAVE_KEY = "game";
179554
- var PREFIX2 = "twn1.";
180137
+ var PREFIX3 = "twn1.";
179555
180138
  var keys = /* @__PURE__ */ new Map();
179556
180139
  function keyFor(who) {
179557
180140
  const id9 = `toil:two-weeks-notice:${who.user}:${who.home}`;
@@ -179565,12 +180148,12 @@ function seal(p, who) {
179565
180148
  const iv = randomBytes(IV);
179566
180149
  const cipher = createCipheriv("aes-256-gcm", keyFor(who), iv, { authTagLength: TAG });
179567
180150
  const body = Buffer.concat([cipher.update(JSON.stringify(p), "utf8"), cipher.final()]);
179568
- return PREFIX2 + Buffer.concat([iv, cipher.getAuthTag(), body]).toString("base64url");
180151
+ return PREFIX3 + Buffer.concat([iv, cipher.getAuthTag(), body]).toString("base64url");
179569
180152
  }
179570
180153
  function unseal(sealed, who) {
179571
- if (!sealed.startsWith(PREFIX2)) return void 0;
180154
+ if (!sealed.startsWith(PREFIX3)) return void 0;
179572
180155
  try {
179573
- const raw3 = Buffer.from(sealed.slice(PREFIX2.length), "base64url");
180156
+ const raw3 = Buffer.from(sealed.slice(PREFIX3.length), "base64url");
179574
180157
  if (raw3.length <= IV + TAG) return void 0;
179575
180158
  const decipher = createDecipheriv("aes-256-gcm", keyFor(who), raw3.subarray(0, IV), { authTagLength: TAG });
179576
180159
  decipher.setAuthTag(raw3.subarray(IV, IV + TAG));
@@ -179581,7 +180164,7 @@ function unseal(sealed, who) {
179581
180164
  }
179582
180165
  }
179583
180166
  function readRaw(path2) {
179584
- if (!existsSync12(path2)) return void 0;
180167
+ if (!existsSync13(path2)) return void 0;
179585
180168
  const parsed = JSON.parse(readFileSync9(path2, "utf8"));
179586
180169
  return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : {};
179587
180170
  }
@@ -179629,10 +180212,10 @@ var version2 = VERSION;
179629
180212
  var contractVersion = CONTRACT_VERSION;
179630
180213
  var served = commands33.filter(servedOverMcp);
179631
180214
  var byName3 = new Map(served.map((def) => [commandName(def), def]));
179632
- var PERSON_COMMANDS = /* @__PURE__ */ new Set(["connections add", "connections login", "connections remove", "connections writes", "connections default", "feedback"]);
180215
+ var PERSON_COMMANDS = /* @__PURE__ */ new Set(["connections add", "connections login", "connections remove", "connections writes", "connections default", "dossiers onboard", "feedback"]);
179633
180216
  var forPerson = commands33.filter((def) => PERSON_COMMANDS.has(commandName(def)));
179634
180217
  var personByName = new Map(forPerson.map((def) => [commandName(def), def]));
179635
- var areaInfo = areas.map((a) => ({ name: a.name, fallbacks: a.fallbacks, contextInputs: Object.keys(a.context) }));
180218
+ var areaInfo = areas.map((a) => ({ name: a.name, fallbacks: a.fallbacks, contextInputs: Object.keys(a.context), ...a.siteApis ? { siteApis: a.siteApis } : {} }));
179636
180219
  var info = (def) => ({
179637
180220
  name: commandName(def),
179638
180221
  tool: toolName(def),
@@ -179684,13 +180267,14 @@ function prompterFor(person3) {
179684
180267
  const answer2 = await person3.ask(question);
179685
180268
  if (answer2 === void 0) throw new ToilError("CANCELLED", `Nothing was saved: "${question.text}" wasn't answered.`, { fix: "Answer every question the command asks, then try again." });
179686
180269
  if (typeof answer2 !== "string") throw new ToilError("INVALID_INPUT", `The answer to "${question.text}" must be text.`, { fix: "Pass the text the person typed." });
179687
- return answer2.trim();
180270
+ return answer2;
179688
180271
  };
179689
180272
  return {
179690
180273
  ask: async (text4, fallback, id9) => {
179691
- const answer2 = await ask({ id: id9 ?? "question", text: text4, secret: false, fallback: fallback ?? null });
180274
+ const answer2 = (await ask({ id: id9 ?? "question", text: text4, secret: false, fallback: fallback ?? null })).trim();
179692
180275
  return answer2 === "" ? fallback ?? "" : answer2;
179693
180276
  },
180277
+ // Untrimmed, as typed: the paste checks (checkSecret) trim it and say so, as on a terminal.
179694
180278
  askSecret: (text4, id9) => ask({ id: id9 ?? "secret", text: text4, secret: true, fallback: null })
179695
180279
  };
179696
180280
  }
@@ -179745,10 +180329,13 @@ function findSimilar2(records, request, options2 = {}) {
179745
180329
  }
179746
180330
  var owiVersion = OWI_VERSION;
179747
180331
  var owiSchema = schema_default;
180332
+ function checkSecret3(raw3, rules) {
180333
+ return checkSecret2(raw3, rules);
180334
+ }
179748
180335
 
179749
180336
  // src/cli.ts
179750
180337
  async function main() {
179751
- const areaInfo2 = areas.map((a) => ({ name: a.name, fallbacks: a.fallbacks, contextInputs: Object.keys(a.context) }));
180338
+ const areaInfo2 = areas.map((a) => ({ name: a.name, fallbacks: a.fallbacks, contextInputs: Object.keys(a.context), ...a.siteApis ? { siteApis: a.siteApis } : {} }));
179752
180339
  const interrupt = new AbortController();
179753
180340
  process.once("SIGINT", () => interrupt.abort());
179754
180341
  const secrets2 = createSecretStore();
@@ -179818,7 +180405,7 @@ async function main() {
179818
180405
  cwd: process.cwd(),
179819
180406
  home: homedir4(),
179820
180407
  areas: areaInfo2,
179821
- catalog: areas.map((a) => ({ name: a.name, description: a.description, signsIn: a.secrets.length > 0, live: Boolean(a.probe && a.request), configurable: Object.keys(a.connection.shape).length > 0, context: Object.keys(a.context), checksDossier: commands33.some((def) => def.path[0] === a.name && def.path[1] === "check-dossier"), commands: commandSummaries(a.name, commands33) })),
180408
+ catalog: areas.map((a) => ({ name: a.name, description: a.description, signsIn: a.secrets.length > 0, live: Boolean(a.probe && a.request), configurable: Object.keys(a.connection.shape).length > 0, context: Object.keys(a.context), ...a.siteApis ? { siteApis: a.siteApis } : {}, checksDossier: commands33.some((def) => def.path[0] === a.name && def.path[1] === "check-dossier"), commands: commandSummaries(a.name, commands33) })),
179822
180409
  mcpAreas: [...new Set(commands33.filter((def) => servedOverMcp(def) && def.kind !== "standalone").map(areaOf))].sort(),
179823
180410
  script: process.argv[1]
179824
180411
  });
@@ -179851,6 +180438,7 @@ async function main() {
179851
180438
  }
179852
180439
  }
179853
180440
  export {
180441
+ checkSecret3 as checkSecret,
179854
180442
  contractVersion,
179855
180443
  execute3 as execute,
179856
180444
  findSimilar2 as findSimilar,