@catheadowl/ukp 0.2.4 → 0.2.6

package/src/commands/init.ts

@@ -139,6 +139,31 @@ function renderServiceManifest(options: { name?: string; description?: string; d
   return encoded.endsWith("\n") ? encoded : `${encoded}\n`;
 }
 
+/** Self-ignore guard for `.ukp/` (O-020 door-family B-b): the folder holds
+ * machine-local Service state (manifest, instance identity, TLS private
+ * keys) that must never enter version control or folder sync. `*` inside
+ * the tool-owned directory is the virtualenv / Python 3.13 venv / Meson
+ * precedent — it never touches the user's repo-root `.gitignore`. An
+ * existing file is never touched, so operators who pre-write their own
+ * ignore policy keep it (e.g. tracking service.toml on purpose). */
+const UKP_SELF_IGNORE = [
+  "# UKP local Service state (manifest, identity, TLS keys) is machine-local:",
+  "# self-ignored to keep it out of version control and folder sync.",
+  "*",
+  "",
+].join("\n");
+
+function ensureUkpSelfIgnore(ukpDirectory: string): void {
+  const gitignorePath = join(ukpDirectory, ".gitignore");
+  if (existsSync(gitignorePath)) return;
+  try {
+    writeFileSync(gitignorePath, UKP_SELF_IGNORE, { flag: "wx", mode: 0o644 });
+  } catch (error) {
+    // Concurrent writer installed the same guard — in place either way.
+    if (!(error instanceof Error) || (error as NodeJS.ErrnoException).code !== "EEXIST") throw error;
+  }
+}
+
 function createServiceManifest(
   currentDirectory: string,
   options: InitServiceOptions,
@@ -169,6 +194,8 @@ function createServiceManifest(
     throw error;
   }
 
+  ensureUkpSelfIgnore(ukpDirectory);
+
   return { folder, manifestPath, name, nameSource };
 }
 

package/src/commands/rg.ts

@@ -3,6 +3,7 @@ import {
   projectRgEnvelope,
   renderRgHuman,
   RG_DEFAULT_LIMIT,
+  RG_FILES_DEFAULT_LIMIT,
   RG_MAX_LIMIT,
   RgPlanningError,
   RgUsageError,
@@ -11,6 +12,7 @@ import {
   type RgAggregateStatus,
   type RgContext,
   type RgEndpointOutcome,
+  type RgMode,
   type RgResult,
 } from "../capabilities/rg.ts";
 import { EXTERNAL_PROVIDER } from "../config/external-tool.ts";
@@ -50,17 +52,19 @@ export const RG_SPEC: UkpCommandSpec = {
   summary: "grep raw endpoint files with ripgrep (no index or declaration needed; results as ukp:// references)",
   group: "endpoint",
   description:
-    "Run base lexical search (ripgrep) across one or more Service endpoints. "
+    "Run base lexical search (ripgrep) across one or more Service endpoints, "
+    + "or enumerate their files with --files. "
     + "Available on every registered endpoint by default; results are shaped into ukp:// references that 'ukp read' consumes directly. "
     + "For indexed/semantic search use 'ukp search'.",
-  usage: "[--endpoint <name> ... | -g] <pattern> [--limit <1-1000>] [--count] [--glob <glob>] [--type <type>] [-i] [-- <rg flags>]",
-  arguments: [{ name: "pattern", help: "one non-empty regex pattern; quote to escape the shell" }],
+  usage: "[--endpoint <name> ... | -g] (<pattern> | --files) [--limit <1-1000>] [--count] [--glob <glob> ...] [--type <type>] [-i] [-- <rg flags>]",
+  arguments: [{ name: "pattern", help: "one non-empty regex pattern; quote to escape the shell (omit with --files)" }],
   options: [
     { flags: "-c, --endpoint <name>", help: "select one endpoint; repeat to select multiple endpoints", multi: true },
     { flags: "-g", help: "search every endpoint in the Host Registry; takes no value" },
-    { flags: "--limit <1-1000>", help: `maximum matches per run (default: ${RG_DEFAULT_LIMIT})` },
+    { flags: "--limit <1-1000>", help: `maximum results per run (default: ${RG_DEFAULT_LIMIT}; ${RG_FILES_DEFAULT_LIMIT} with --files)` },
     { flags: "--count", help: "count mode: per-file match counts instead of matches" },
-    { flags: "--glob <glob>", help: "glob filter passed to rg (e.g. \"*.md\")" },
+    { flags: "--files", help: "files mode: enumerate files by tree walk with no pattern (empty and binary files included; combine with --glob/--type)" },
+    { flags: "--glob <glob>", help: "glob filter passed to rg (e.g. \"*.md\"); repeat to combine - a later glob may negate with !", multi: true },
     { flags: "--type <type>", help: "file type filter passed to rg (e.g. md, py)" },
     { flags: "-i", help: "case-insensitive search" },
     { flags: "--json", help: "emit the structured response envelope" },
@@ -69,7 +73,8 @@ export const RG_SPEC: UkpCommandSpec = {
     "",
     "Passthrough:",
     "  After '--', rg native flags are passed through on an allowlist",
-    "  (-A/-B/-C/-m/--glob/--type/--max-filesize and common boolean flags).",
+    "  (-A/-B/-C/-m/--glob/--iglob/--type/--max-filesize and common boolean",
+    "  flags).",
     "  Path operands and output-changing flags (--json, -r, --pre, --config)",
     "  are rejected: the endpoint selector owns scope, UKP owns the output.",
     "",
@@ -84,6 +89,12 @@ export const RG_SPEC: UkpCommandSpec = {
     "  'ukp search' covers indexed search where the Service declares a search",
     "  capability provider.",
     "",
+    "Visibility:",
+    "  Every rg mode skips hidden files (dot-prefixed, including the .ukp/",
+    "  wiring) by default; pass -- --hidden after '--' to include them",
+    "  (-uu additionally lifts .gitignore rules). --files lists every",
+    "  non-hidden file, including empty and binary ones.",
+    "",
   ].join("\n"),
 };
 
@@ -92,7 +103,8 @@ interface RgCommandOptions extends Record<string, unknown> {
   g?: boolean;
   limit?: string;
   count?: boolean;
-  glob?: string;
+  files?: boolean;
+  glob?: string[];
   type?: string;
   i?: boolean;
   json?: boolean;
@@ -102,10 +114,13 @@ export function parseRgArgs(args: readonly string[]): ParsedRg {
   const parsed = parseKitArgs<RgCommandOptions>(RG_SPEC, args);
   const explicit: string[] = [];
   const warnings: string[] = [];
+  const files = parsed.options.files === true;
 
   // Command-side semantic checks, in the pre-kit order: limit validation,
-  // duplicate warnings, excess positional, emptiness, conflict.
-  let limit = RG_DEFAULT_LIMIT;
+  // duplicate warnings, excess positional, mode conflicts, pattern rule,
+  // scope conflict. Files mode (ADR-RG-005) relaxes the pattern requirement
+  // and rejects combinations that would silently no-op.
+  let limit = files ? RG_FILES_DEFAULT_LIMIT : RG_DEFAULT_LIMIT;
   if (parsed.options.limit !== undefined) {
     if (!/^[0-9]+$/.test(parsed.options.limit)) throw new KitUsageError("--limit must be a decimal integer");
     limit = Number(parsed.options.limit);
@@ -125,20 +140,34 @@ export function parseRgArgs(args: readonly string[]): ParsedRg {
       `unexpected argument '${unexpected}'; rg accepts exactly one pattern. Use '--endpoint <name>' to select an endpoint; '-g' takes no value.`,
     );
   }
-  if (pattern === undefined || pattern.length === 0) throw new KitUsageError("rg pattern must be non-empty");
+  if (files && parsed.options.count === true) {
+    throw new KitUsageError("--files and --count cannot be used together (pick one output mode)");
+  }
+  if (files && parsed.options.i === true) {
+    throw new KitUsageError("--files cannot be combined with -i: there is no pattern to match; pass '-- --iglob <glob>' for a case-insensitive glob filter");
+  }
+  if (files) {
+    if (pattern !== undefined) {
+      throw new KitUsageError(`unexpected argument '${pattern}'; --files takes no pattern - use --glob to filter by name`);
+    }
+  } else if (pattern === undefined || pattern.length === 0) {
+    throw new KitUsageError("rg pattern must be non-empty (or pass --files to enumerate files without a pattern)");
+  }
   if (parsed.options.g && explicit.length > 0) {
     throw new KitUsageError("--endpoint and -g cannot be used together");
   }
 
+  const globs = parsed.options.glob ?? [];
   return {
-    request: { query: pattern, limit },
+    request: { query: files ? "" : pattern!, limit },
     options: {
       explicitEndpoints: explicit.length > 0 ? explicit : undefined,
       global: parsed.options.g ?? false,
-      ...(parsed.options.glob === undefined ? {} : { glob: parsed.options.glob }),
+      ...(globs.length > 0 ? { globs } : {}),
       ...(parsed.options.type === undefined ? {} : { type: parsed.options.type }),
       ...(parsed.options.i === true ? { ignoreCase: true } : {}),
       ...(parsed.options.count === true ? { count: true } : {}),
+      ...(files ? { files: true } : {}),
       ...(parsed.options.json === true ? { json: true } : {}),
       passthrough: [],
     },
@@ -238,7 +267,7 @@ function renderRgCommandResult(parsed: ParsedRg, result: RgResult): RgCommandRes
   if (parsed.options.json === true) {
     return {
       exitCode: RG_EXIT_BY_AGGREGATE[result.aggregate],
-      stdout: `${JSON.stringify(projectRgEnvelope(result, parsed.options.count === true), null, 2)}\n`,
+      stdout: `${JSON.stringify(projectRgEnvelope(result), null, 2)}\n`,
       stderr: view.diagnostics,
     };
   }
@@ -305,10 +334,11 @@ async function executeMixedRg(
         const execution = await remoteRg(binding, transport, token, {
           query: parsed.request.query,
           limit: parsed.request.limit,
-          ...(parsed.options.glob !== undefined ? { glob: parsed.options.glob } : {}),
+          ...(parsed.options.globs !== undefined ? { globs: parsed.options.globs } : {}),
           ...(parsed.options.type !== undefined ? { type: parsed.options.type } : {}),
           ...(parsed.options.ignoreCase === true ? { ignoreCase: true } : {}),
           ...(parsed.options.count === true ? { count: true } : {}),
+          ...(parsed.options.files === true ? { files: true } : {}),
           passthrough: parsed.options.passthrough,
         });
         remoteOutcomes.set(binding.name, execution.outcome);
@@ -343,6 +373,7 @@ async function executeMixedRg(
   return renderRgCommandResult(parsed, {
     query: parsed.request.query,
     limit: parsed.request.limit,
+    mode: (parsed.options.files === true ? "files" : parsed.options.count === true ? "count" : "match") as RgMode,
     endpoints,
     warnings,
     aggregate,

package/src/commands/serve-task.ts

@@ -2,18 +2,59 @@
  * renders the process-manager artifacts for an https door on a Windows host
  * — the start script, the hidden launcher (vbs), the Task Scheduler command,
  * the firewall rule — as text the operator reviews and applies. Print-only
- * by construction: UKP installs nothing, starts nothing, and never sees the
- * real token (the script line carries a placeholder; the operator pastes the
- * token into the file they save, under their own permission regime).
+ * by default: UKP installs nothing, starts nothing, and the printed script
+ * line carries a placeholder (the operator pastes the token into the file
+ * they save, under their own permission regime).
  *
- * The emitted shapes mirror the machine-verified liku recipe (deployment
- * handbook, Windows section): a bare `ukp` resolves through the logged-on
- * task's per-user PATH and the self-locating launcher finds bun itself, so
- * no PATH export is emitted. The hidden launcher is the product default
- * (owner ruling 2026-09-21: a visibly popping cmd window is not a correct
- * product form): zero flash (hidden at process creation), door.log capture,
+ * `--print-task --write` (O-020 ruling C, 2026-09-23 owner verdict: the
+ * D-090 secret-free clause scopes to the print surface) swaps the two file
+ * artifacts' sink from stdout to disk: the same bodies land as
+ * `%USERPROFILE%\.ukp\start-door.cmd` + `start-door-hidden.vbs`, CRLF, with
+ * the token interpolated from `UKP_SERVE_TOKEN` (never displayed, never in
+ * argv, refused outright if it carries characters that would corrupt a cmd
+ * file). Existing files are never overwritten - operator edits (PATH
+ * patches) live there; regeneration goes through the removal recipe. The
+ * remaining steps stay on stdout: register the task, open the firewall,
+ * verify with `ukp diagnose --door`. Still nothing is installed, started,
+ * or uninstalled by UKP.
+ *
+ * The emitted shapes mirror the field-verified recipes (deployment
+ * handbook, Windows section; provider round 2026-09-23): a bare `ukp`
+ * resolves through the logged-on task's per-user PATH and the
+ * self-locating launcher finds bun itself, so no PATH export is emitted.
+ * The hidden launcher is the product default (owner ruling 2026-09-21: a
+ * visibly popping cmd window is not a correct product form): zero flash
+ * (hidden at process creation), sole door.log capture (ISSUE-016: a
+ * redirect on the cmd's serve line too deadlocks the nested append-open),
  * exit-code propagation, bounded crash retry — Task Scheduler's own
- * restart-on-failure does not fire on exit codes (disproven on liku). */
+ * restart-on-failure does not fire on exit codes (disproven on liku). The
+ * scheduled task registers unelevated via a per-user logon trigger with
+ * no execution time limit (the scheduler's 72h default silently kills
+ * resident doors).
+ *
+ * Riders 2026-09-23 (O-020 ruling A, copy-only): single-endpoint prints
+ * name the whole-registry host-door alternative (one door instead of one
+ * port per endpoint), the self-signed notes add the task-PATH openssl gap
+ * (the logged-on task may lack the shell's openssl source; Git for
+ * Windows' mingw64\bin is named as the common remedy, no hardcoded path),
+ * and every print carries the stop-before-editing hazard (a running cmd
+ * re-reads the script at a stale byte offset).
+ *
+ * §5 "To remove the door" (2026-09-23, O-020 ruling B1 / teardown FR):
+ * the print's own inverse, three levels — stop now (the same launcher-root
+ * kill as the restart note), stop for good (Unregister-ScheduledTask:
+ * confirms by default, and does NOT stop the running instance), erase
+ * everything (the reverse of steps 4→0, firewall rule included, the
+ * token-bearing cmd named, self-signed identity located by door shape —
+ * the single-endpoint identity sits INSIDE the served folder, so sync
+ * carries the private key out). The scheduler's own End/Stop task route
+ * is deliberately absent: it does not kill the tree (disproven in the
+ * field). Print-only as ever — the removal advice documents, never
+ * executes. */
+
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { KitUsageError } from "./kit.ts";
 
 export interface ServeTaskTlsSelfSigned {
   mode: "self-signed";
@@ -31,6 +72,9 @@ export type ServeTaskTls = ServeTaskTlsSelfSigned | ServeTaskTlsCertificates;
 export interface ServeTaskInput {
   /** Present = single-endpoint mode; absent = host door mode. */
   endpoint?: string;
+  /** Subset door (ADR-REM-010): the mirrored --select names; the §1 serve
+   * line carries them so the resident door serves the same subset. */
+  select?: readonly string[];
   host: string;
   port: number;
   tls?: ServeTaskTls;
@@ -71,6 +115,7 @@ function serveCommandLine(input: ServeTaskInput): string {
   return [
     "ukp serve",
     ...(input.endpoint !== undefined ? [`--endpoint ${input.endpoint}`] : []),
+    ...(input.select !== undefined ? [`--select ${input.select.join(",")}`] : []),
     `--host ${input.host}`,
     `--port ${input.port}`,
     ...tls,
@@ -83,8 +128,87 @@ function parentDirOf(path: string): string | undefined {
   return cut > 0 ? path.slice(0, cut) : undefined;
 }
 
+/** The start script's file body, unindented — the single source both the
+ * print form (indented embed, `<paste-your-token>` slot) and `--write`
+ * (bytes on disk, real token) render. `written` switches the token rem
+ * lines to the written-file provenance so the file reads truthfully about
+ * where its secret came from. */
+export function startDoorCmdBody(
+  input: ServeTaskInput,
+  tokenSlot: string,
+  written: boolean,
+): string[] {
+  return [
+    "@echo off",
+    "rem UKP resident door (generated by ukp serve --print-task)",
+    ...(written
+      ? [
+          "rem The token line is the only secret: --write interpolated it",
+          "rem from UKP_SERVE_TOKEN (never displayed). Keep this file",
+          "rem private; deleting it destroys this copy.",
+        ]
+      : [
+          "rem The token line is the only secret: mint a long random string",
+          "rem (e.g. openssl rand -hex 32), paste it in, keep this file private.",
+        ]),
+    `set "UKP_SERVE_TOKEN=${tokenSlot}"`,
+    "rem ukp resolves through the logged-on task's per-user PATH; the",
+    "rem launcher finds bun itself - no PATH export needed.",
+    'if not exist "%USERPROFILE%\\.ukp" mkdir "%USERPROFILE%\\.ukp"',
+    "rem logging is owned by start-door-hidden.vbs (outer redirect) - a",
+    "rem second redirect to the same file here deadlocks the append open",
+    serveCommandLine(input),
+  ];
+}
+
+/** The hidden launcher's file body, unindented (print embeds it indented;
+ * --write writes these lines as-is). Carries no secret - the token lives
+ * only in start-door.cmd. */
+export function startDoorVbsBody(): string[] {
+  return [
+    "' UKP door hidden launcher: runs start-door.cmd with NO visible",
+    "' window (hidden at process creation - nothing flashes), captures",
+    "' everything to door.log, waits out the door's lifetime, propagates",
+    "' its exit code, and retries a crashed door 3 times, 30s apart.",
+    'Dim shell : Set shell = CreateObject("WScript.Shell")',
+    "Dim q : q = Chr(34)",
+    'Dim home : home = shell.ExpandEnvironmentStrings("%USERPROFILE%")',
+    'Dim cmdline : cmdline = "cmd /c " & q & q & home & "\\.ukp\\start-door.cmd" & q & " >> " & q & home & "\\.ukp\\door.log" & q & " 2>&1" & q',
+    "Dim rc : rc = 0",
+    "Dim attempt",
+    "For attempt = 1 To 3",
+    "  rc = shell.Run(cmdline, 0, True)",
+    "  If rc = 0 Then Exit For",
+    "  If attempt < 3 Then WScript.Sleep 30000",
+    "Next",
+    "WScript.Quit rc",
+  ];
+}
+
+/** Task-registration step (PowerShell, unelevated) - shared by the print
+ * form's step 3 and the --write report's next steps. */
+function taskRegistrationLines(): string[] {
+  return [
+    '$t = New-ScheduledTaskTrigger -AtLogOn -User "$env:USERDOMAIN\\$env:USERNAME"',
+    "$s = New-ScheduledTaskSettingsSet -AllowStartIfOnBatteries `",
+    "-DontStopIfGoingOnBatteries -MultipleInstances IgnoreNew `",
+    "-ExecutionTimeLimit ([TimeSpan]::Zero)",
+    "Register-ScheduledTask -TaskName 'ukp-door' -Action (New-ScheduledTaskAction `",
+    "-Execute 'wscript.exe' -Argument '\"%USERPROFILE%\\.ukp\\start-door-hidden.vbs\"') `",
+    "-Trigger $t -Settings $s -Force",
+    "Start-ScheduledTask -TaskName ukp-door",
+  ];
+}
+
+function firewallRuleLine(port: number): string {
+  return `netsh advfirewall firewall add rule name="ukp-door" dir=in action=allow protocol=TCP localport=${port}`;
+}
+
+function indent3(lines: readonly string[]): string[] {
+  return lines.map((line) => `   ${line}`);
+}
+
 export function renderServeTaskArtifacts(input: ServeTaskInput): string {
-  const serveLine = serveCommandLine(input);
   const out: string[] = [
     "ukp serve --print-task - Windows resident-door artifacts",
     "",
@@ -119,49 +243,91 @@ export function renderServeTaskArtifacts(input: ServeTaskInput): string {
     "   (write it with a real editor and CRLF line endings; writing cmd",
     "   files over ssh echo mangles % escaping)",
     "",
-    "   @echo off",
-    "   rem UKP resident door (generated by ukp serve --print-task)",
-    "   rem The token line is the only secret: mint a long random string",
-    "   rem (e.g. openssl rand -hex 32), paste it in, keep this file private.",
-    "   set \"UKP_SERVE_TOKEN=<paste-your-token>\"",
-    "   rem ukp resolves through the logged-on task's per-user PATH; the",
-    "   rem launcher finds bun itself - no PATH export needed.",
-    "   if not exist \"%USERPROFILE%\\.ukp\" mkdir \"%USERPROFILE%\\.ukp\"",
-    `   ${serveLine} >> "%USERPROFILE%\\.ukp\\door.log" 2>&1`,
+    ...indent3(startDoorCmdBody(input, "<paste-your-token>", false)),
     "",
     "2) Hidden launcher - save as %USERPROFILE%\\.ukp\\start-door-hidden.vbs",
     "   (CRLF and a real editor again: the vbs carries literal % signs that",
     "   ssh echo would expand - copy the file instead)",
     "",
-    "   ' UKP door hidden launcher: runs start-door.cmd with NO visible",
-    "   ' window (hidden at process creation - nothing flashes), captures",
-    "   ' everything to door.log, waits out the door's lifetime, propagates",
-    "   ' its exit code, and retries a crashed door 3 times, 30s apart.",
-    "   Dim shell : Set shell = CreateObject(\"WScript.Shell\")",
-    "   Dim q : q = Chr(34)",
-    "   Dim home : home = shell.ExpandEnvironmentStrings(\"%USERPROFILE%\")",
-    "   Dim cmdline : cmdline = \"cmd /c \" & q & q & home & \"\\.ukp\\start-door.cmd\" & q & \" >> \" & q & home & \"\\.ukp\\door.log\" & q & \" 2>&1\" & q",
-    "   Dim rc : rc = 0",
-    "   Dim attempt",
-    "   For attempt = 1 To 3",
-    "     rc = shell.Run(cmdline, 0, True)",
-    "     If rc = 0 Then Exit For",
-    "     If attempt < 3 Then WScript.Sleep 30000",
-    "   Next",
-    "   WScript.Quit rc",
+    ...indent3(startDoorVbsBody()),
     "",
     "3) Scheduled task - starts the door at LOGON, hidden",
-    "   (create it from an elevated shell: creating an ONLOGON task from a",
-    "    plain shell fails with Access denied)",
+    "   (run this block in PowerShell; no elevation needed: this per-user",
+    "   logon trigger registers from a plain shell. A machine-level logon",
+    "   trigger or another user's session still needs the elevated",
+    "   schtasks route)",
     "",
-    "   schtasks /Create /TN ukp-door /TR \"wscript.exe \\\"%USERPROFILE%\\.ukp\\start-door-hidden.vbs\\\"\" /SC ONLOGON /F",
-    "   schtasks /Run /TN ukp-door",
+    ...indent3(taskRegistrationLines()),
     "",
     "4) Firewall rule for the port (from an elevated shell)",
     "",
-    `   netsh advfirewall firewall add rule name="ukp-door" dir=in action=allow protocol=TCP localport=${input.port}`,
+    `   ${firewallRuleLine(input.port)}`,
+    "",
+    "5) To remove the door - stopping it is not disabling it, and",
+    "   disabling it is not erasing it. Three levels; go as far as you",
+    "   mean to.",
+    "",
+    "   Stop it NOW: kill the LAUNCHER root - the same command as the",
+    "   restart note in the Notes below:",
+    "   taskkill /PID <wscript-pid> /T /F",
+    "   The door stays down until the next logon or a manual Start; with",
+    "   the task still registered, the next logon brings it back.",
+    "",
+    "   Stop it FOR GOOD: delete the scheduled task step 3 registered",
+    "   (ukp-door in this printout - a renamed second door has its own",
+    "   name), from a plain shell, the same zero-elevation path as",
+    "   registering it:",
+    "   Unregister-ScheduledTask -TaskName ukp-door -Confirm:$false",
+    "   The cmdlet asks for confirmation by default; unregistering does",
+    "   NOT kill a running door - the kill above is not optional.",
+    "",
+    "   Erase EVERYTHING - the reverse of steps 4 -> 0 (the firewall",
+    "   delete needs the elevated shell again):",
+    '   netsh advfirewall firewall delete rule name="ukp-door"',
+    // Comma-separated paths: cmd's native delimiter AND PowerShell's
+    // array argument (a space-separated del line binds only the first
+    // path in PowerShell - caught live in the 2026-09-23 drill).
+    '   del "%USERPROFILE%\\.ukp\\start-door.cmd", "%USERPROFILE%\\.ukp\\door.log"',
+    '   del "%USERPROFILE%\\.ukp\\start-door-hidden.vbs"',
+    "   start-door.cmd carries the token in plaintext: deleting it",
+    "   destroys this copy, but if it ever left this machine (a backup,",
+    "   a copy), treat the token as burned and mint a fresh one for any",
+    "   future door.",
+    ...(input.tls?.mode === "certificates"
+      ? [
+          `   del "${input.tls.keyPath}" "${input.tls.certPath}"`,
+          "   (the certificate paths step 0 printed)",
+        ]
+      : []),
+    ...(input.tls?.mode === "self-signed" && input.endpoint !== undefined
+      ? [
+          "   The --tls identity lives in the served folder's .ukp\\tls\\ -",
+          "   INSIDE the knowledge folder. Git or cloud sync",
+          "   carries the private key out with it. Delete it when the folder",
+          "   leaves this machine; ukp init service drops a self-ignoring",
+          "   .ukp\\.gitignore there for exactly this reason.",
+        ]
+      : []),
+    ...(input.tls?.mode === "self-signed" && input.endpoint === undefined
+      ? [
+          "   The --tls identity is host-local: the tls\\ folder beside the",
+          "   host registry - delete it with the door if you are done.",
+        ]
+      : []),
+    "   The endpoints stay registered on the host for local use;",
+    "   unregister them too only if you are done with them, one per",
+    "   endpoint: ukp unregister --endpoint <name>. Every consumer that",
+    "   ran ukp register --url holds the token in plaintext in its own",
+    "   registry - run ukp unregister --endpoint <name> there as well.",
     "",
     "Notes:",
+    ...(input.endpoint !== undefined
+      ? [
+          "- Single-endpoint door (one port, task, and token per endpoint):",
+          "  omit --endpoint to serve the whole registry as one host door",
+          "  (/e/<name>/ routing, all endpoints, one port).",
+        ]
+      : []),
     ...(input.tls?.mode === "self-signed"
       ? [
           "- --tls self-signs at first start using an openssl on PATH (Git",
@@ -169,6 +335,11 @@ export function renderServeTaskArtifacts(input: ServeTaskInput): string {
           "  anywhere, pre-generate the certificate once instead: re-run with",
           "  --tls-cert/--tls-key - the handbook's Windows section carries",
           "  that recipe.",
+          "- The task's PATH is not your shell's: the logged-on task",
+          "  environment may lack the openssl source your interactive shell",
+          "  sees (--tls then fails to self-sign or re-sign). The common",
+          "  source is Git for Windows' mingw64\\bin - extend PATH inside",
+          "  start-door.cmd: set \"PATH=%PATH%;<git>\\mingw64\\bin\".",
         ]
       : []),
     "- No visible window, by design: the hidden launcher starts the console",
@@ -180,15 +351,35 @@ export function renderServeTaskArtifacts(input: ServeTaskInput): string {
     "  failure visible (non-zero task result + door.log). Do not rely on",
     "  Task Scheduler's restart-on-failure setting - it does not fire on",
     "  exit codes.",
+    "- The task recipe pins no execution time limit on purpose: the Task",
+    "  Scheduler default stops a task 72 hours after it starts, which",
+    "  would silently kill a resident door (no window, no log line).",
     "- To restart the door by hand (new token, ukp upgrade, new cert):",
-    "  taskkill /PID <door-pid> /T /F, then schtasks /Run /TN ukp-door",
-    "  (schtasks /End does not reliably kill the process tree).",
+    "  kill the LAUNCHER root, not just the serve leaf. The kill command:",
+    "  taskkill /PID <wscript-pid> /T /F - where <wscript-pid> is the",
+    "  wscript.exe running start-door-hidden.vbs; then",
+    "  Start-ScheduledTask -TaskName ukp-door. A leaf-only kill lets",
+    "  the launcher's bounded retry re-grab the port within 30s, racing",
+    "  your Start (which IgnoreNew no-ops while the old launcher lives);",
+    "  the scheduler's End-Task does not kill the tree either. Each door",
+    "  has its own wscript - in PowerShell, list them and match the vbs",
+    "  name: Get-CimInstance Win32_Process -Filter \"Name='wscript.exe'\"",
+    "  | Select-Object ProcessId,CommandLine",
+    "- Git Bash users: prefix slash-style commands with MSYS_NO_PATHCONV=1",
+    "  (e.g. MSYS_NO_PATHCONV=1 taskkill /PID <pid> /T /F), or MSYS rewrites",
+    "  the slash arguments into Git paths and the command fails with a",
+    "  misleading Invalid-argument error.",
     "- LOGON, not boot: the door starts when someone logs on - nobody",
     "  logged on means no door. Unattended-boot always-on needs a service",
     "  wrapper (WinSW-class) - deliberately outside this recipe; prefer the",
     "  ssh:// path or a Linux host (systemd socket activation) for that.",
+    "- Stop the door before editing start-door.cmd: a running cmd",
+    "  re-reads the script from a stale byte offset when the current",
+    "  line's child exits, so editing lines above can make it execute",
+    "  torn fragments of the edit.",
     "- Re-run ukp serve --print-task with different flags to regenerate;",
-    "  edits land by saving the files and re-running schtasks /Run.",
+    "  edits land by saving the files and starting the task again",
+    "  (Start-ScheduledTask -TaskName ukp-door).",
     "- Full recipes and hardening: the deployment handbook -",
     "  docs/remote-deployment.md in this package, or",
     "  https://github.com/CatheadOwl/ukp/blob/main/docs/remote-deployment.md",
@@ -196,3 +387,102 @@ export function renderServeTaskArtifacts(input: ServeTaskInput): string {
   );
   return out.join("\n");
 }
+
+/** Characters that would corrupt the written cmd file: a quote breaks the
+ * `set "..."` quoting, a percent sign pairs into cmd's parse-time
+ * expansion, any control character can tear the file into lines. This is
+ * the third-live-observed hand-error class (printf `\b` mangling the PATH
+ * line, 2026-09-23) refused by construction - minted hex tokens (openssl
+ * rand -hex 32) always pass. Returns the problem description, not the
+ * token: the value is never echoed anywhere. */
+export function unsafeTokenReason(token: string): string | undefined {
+  for (const ch of token) {
+    if (ch === '"') return "a double quote (it would break the script's set quoting)";
+    if (ch === "%") return "a percent sign (cmd expands % pairs at parse time)";
+    const code = ch.codePointAt(0)!;
+    if (code < 0x20 || code === 0x7f) return "a control character (it would tear the file into lines)";
+  }
+  return undefined;
+}
+
+function crlf(lines: readonly string[]): string {
+  return `${lines.join("\r\n")}\r\n`;
+}
+
+/** `--print-task --write` (O-020 ruling C): the two file artifacts land on
+ * disk under `<home>\\.ukp\\` with the env token interpolated, CRLF line
+ * endings by construction. Existing files are never overwritten (operator
+ * edits like PATH patches live in the cmd); anything already there aborts
+ * the whole write before the first byte. Throws KitUsageError for
+ * invocation-level token problems, Error for the existing-file refusal.
+ * Returns the stdout report - composed only from token-free pieces, so the
+ * token exists in exactly one place: the cmd file's bytes. */
+export function writeServeTaskArtifacts(
+  input: ServeTaskInput,
+  options: { token: string | undefined; homeDir: string },
+): string {
+  if (options.token === undefined || options.token.length === 0) {
+    throw new KitUsageError(
+      "--write needs the door token in the environment: set UKP_SERVE_TOKEN (mint one, e.g. openssl rand -hex 32) - the generator never invents or displays it",
+    );
+  }
+  const unsafe = unsafeTokenReason(options.token);
+  if (unsafe !== undefined) {
+    throw new KitUsageError(
+      `--write refuses this UKP_SERVE_TOKEN: it contains ${unsafe} - mint a token without such characters (e.g. openssl rand -hex 32); the value itself is never echoed`,
+    );
+  }
+  const dir = join(options.homeDir, ".ukp");
+  const cmdPath = join(dir, "start-door.cmd");
+  const vbsPath = join(dir, "start-door-hidden.vbs");
+  const existing = [cmdPath, vbsPath].filter((path) => existsSync(path));
+  if (existing.length > 0) {
+    throw new Error(
+      `refusing to overwrite ${existing.join(", ")}: --write never clobbers existing files (operator edits like PATH patches live there) - remove them first (the print-only form's section 5 carries the removal recipe) or keep hand-saving the printed form`,
+    );
+  }
+  mkdirSync(dir, { recursive: true });
+  // The cmd carries the token: 0600 like every other secret-bearing file
+  // this CLI writes (the vbs is inert). CRLF, not the platform default -
+  // the same ending the print form begs the operator to preserve by hand.
+  writeFileSync(cmdPath, crlf(startDoorCmdBody(input, options.token, true)), { mode: 0o600 });
+  writeFileSync(vbsPath, crlf(startDoorVbsBody()), { mode: 0o644 });
+  const printInvocation = serveCommandLine(input).replace("ukp serve", "ukp serve --print-task");
+  return [
+    "ukp serve --print-task --write - door artifacts written",
+    "",
+    `  wrote: ${cmdPath}`,
+    "         (the token line was interpolated from UKP_SERVE_TOKEN;",
+    "         it is never displayed - lose the file, lose the token)",
+    `  wrote: ${vbsPath}`,
+    "",
+    "Nothing was registered, started, or opened - apply the rest yourself:",
+    "",
+    "  register the task (PowerShell, no elevation needed):",
+    ...indent2(taskRegistrationLines()),
+    "",
+    "  firewall rule for the port (from an elevated shell):",
+    `    ${firewallRuleLine(input.port)}`,
+    "",
+    ...(input.tls?.mode === "certificates"
+      ? [
+          "  the certificate and key paths written into the script must",
+          "  exist before the door starts (the print-only form's step 0",
+          "  generates them once):",
+          `    ${printInvocation}`,
+          "",
+        ]
+      : []),
+    "  then verify once applied: ukp diagnose --door",
+    "",
+    "Restart recipes, crash behavior, and the removal section live in the",
+    "print-only form and the deployment handbook:",
+    `  ${printInvocation}`,
+    "  docs/remote-deployment.md (in this package)",
+    "",
+  ].join("\n");
+}
+
+function indent2(lines: readonly string[]): string[] {
+  return lines.map((line) => `    ${line}`);
+}