@catheadowl/ukp 0.2.6 → 0.3.0

package/src/cli.ts

@@ -13,6 +13,7 @@ import { executeReadCommand, READ_SPEC } from "./commands/read.ts";
 import { executeRgCommand, RG_SPEC } from "./commands/rg.ts";
 import { executeGuideCommand, GUIDE_SPEC, GUIDE_TOPICS } from "./commands/guide.ts";
 import { executeInitCommand, INIT_SPEC } from "./commands/init.ts";
+import { executeSessionCommand } from "./commands/session.ts";
 import { executeInspectCommand, INSPECT_SPEC } from "./commands/inspect.ts";
 import { executeListCommand, executeRegisterCommand, executeUnregisterCommand, LIST_SPEC, REGISTER_SPEC, UNREGISTER_SPEC } from "./commands/inventory.ts";
 import { executeNavCommand, NAV_SPEC } from "./commands/nav.ts";
@@ -20,6 +21,7 @@ import { executeProposeCommand, PROPOSE_SPEC } from "./commands/propose.ts";
 import { executeUpdateCommand, UPDATE_SPEC } from "./commands/update.ts";
 import { executeServeCommand, SERVE_SPEC } from "./commands/serve.ts";
 import { executeSearchCommand, SEARCH_SPEC } from "./commands/search.ts";
+import { executeUseCommand, USE_SPEC } from "./commands/use.ts";
 
 export { renderSearchHelp } from "./commands/search.ts";
 export { renderDiagnoseHelp } from "./commands/diagnose.ts";
@@ -54,6 +56,7 @@ const COMMAND_DESCRIPTIONS: Record<string, string> = {
   register: REGISTER_SPEC.summary,
   unregister: UNREGISTER_SPEC.summary,
   list: LIST_SPEC.summary,
+  use: USE_SPEC.summary,
   nav: NAV_SPEC.summary,
   propose: PROPOSE_SPEC.summary,
   search: SEARCH_SPEC.summary,
@@ -66,7 +69,10 @@ export const COMMANDS = Object.entries(COMMAND_DESCRIPTIONS).map(
 
 // Help-display groups (ADR 0022): purpose-noun headings over a flat verb
 // surface. Every command must appear in exactly one group; a guard test
-// locks group membership against COMMANDS.
+// locks group membership against COMMANDS. `session` is deliberately
+// outside the advertised surface (owner ruling 2026-11-03, extending the
+// 2026-10-31 contract-face exit): dispatch stays live, the skill face
+// documents it — hidden but functional, the clig.dev shape.
 export const COMMAND_GROUPS = [
   {
     heading: "Endpoint commands",
@@ -74,7 +80,7 @@ export const COMMAND_GROUPS = [
   },
   {
     heading: "Registry commands",
-    commands: ["init", "register", "unregister", "list"],
+    commands: ["init", "register", "unregister", "list", "use"],
   },
   {
     heading: "Operations commands",
@@ -92,6 +98,9 @@ export interface CliContext {
   resolveProvider?: ProviderResolver;
   qmdCommand?: readonly string[];
   rgCommand?: readonly string[];
+  /** Overrides the amux binary behind `ukp session` (wrapper mechanism,
+   * rg.ts rgCommand precedent). */
+  amuxCommand?: readonly string[];
   artifactRoot?: string;
   artifactRunId?: string;
   now?: Date;
@@ -200,7 +209,9 @@ export function renderHelp(): string {
       ),
       "",
     ]),
-    "Endpoint names for --endpoint come from 'ukp list'.",
+    "Endpoint names for --endpoint come from 'ukp list -g' (every registered endpoint); plain 'ukp list' shows the workspace scope.",
+    "",
+    "ukp:// references (ukp://<endpoint>/<path>) address registered endpoints, not web pages; open one with 'ukp read <uri>'.",
     "",
     "A Service's declared capabilities are backed by a provider (QMD, an external tool, backs search and update today); rg and nav work on endpoint files directly, no provider needed.",
     "",
@@ -226,51 +237,6 @@ function writeCommandResult(
   return result.exitCode;
 }
 
-/** Channel philosophy for `ukp list` (ukp_list W2): stdout is the data
- * channel — byte contract, one row per line, the terminal wraps what it
- * must; stderr to an INTERACTIVE terminal is the human channel — progress
- * frames already live there, and the footnote lines (degradation warnings,
- * drift notes) may exceed any terminal width (pins are ~44 chars, urls
- * longer), so the terminal would otherwise break them mid-word or
- * mid-hash. This wraps them at word boundaries (over-long tokens
- * hard-split at the width) — only when the emitter knows the width;
- * piped/CI stderr keeps raw single lines, the machine-parseable form. */
-export function wrapLinesForTerminal(text: string, columns: number): string {
-  if (!Number.isSafeInteger(columns) || columns < 8) return text;
-  const wrapped: string[] = [];
-  for (const line of text.split("\n")) {
-    if (line.length <= columns) {
-      wrapped.push(line);
-      continue;
-    }
-    let current = "";
-    for (const token of line.split(" ")) {
-      // A token longer than the width hard-splits at the width (paths and
-      // SPKI pins have no spaces to break on); the remainder re-enters the
-      // same greedy fill so following words still pack.
-      const pieces: string[] = [];
-      let rest = token;
-      while (rest.length > columns) {
-        pieces.push(rest.slice(0, columns));
-        rest = rest.slice(columns);
-      }
-      pieces.push(rest);
-      for (const piece of pieces) {
-        if (current.length === 0) {
-          current = piece;
-        } else if (current.length + 1 + piece.length <= columns) {
-          current += ` ${piece}`;
-        } else {
-          wrapped.push(current);
-          current = piece;
-        }
-      }
-    }
-    wrapped.push(current);
-  }
-  return wrapped.join("\n");
-}
-
 function executeVersionCommand(args: readonly string[]): CliCommandResult {
   if (args.length === 0) {
     return { exitCode: 0, stdout: renderVersion(), stderr: "" };
@@ -370,6 +336,13 @@ export function runCli(
     }), stdout, stderr);
   }
 
+  if (command === "session") {
+    return writeCommandResultMaybeAsync(executeSessionCommand(args.slice(1), {
+      registryPath,
+      amuxCommand: context.amuxCommand,
+    }), stdout, stderr);
+  }
+
   if (command === "guide") {
     return writeCommandResult(executeGuideCommand(args.slice(1)), stdout, stderr);
   }
@@ -419,22 +392,21 @@ export function runCli(
     }), stdout, stderr);
   }
 
+  if (command === "use") {
+    return writeCommandResult(executeUseCommand(args.slice(1), {
+      currentDirectory,
+      registryPath,
+    }), stdout, stderr);
+  }
+
   if (command === "list") {
     // Streaming delivery (ukp_list W2 / ADR 0026 rule 3): line-by-line
     // through the same stdout writer every other print uses (console.log
     // per line ≡ the single print's trailing-newline form, so piped bytes
     // match the returned-text contract); progress frames only on an
-    // interactive stderr, so piped runs stay progress-silent. The stderr
-    // footnotes wrap at the terminal width there too — piped stderr keeps
-    // the raw single lines (wrapLinesForTerminal's contract).
-    const stderrColumns = process.stderr.columns ?? process.stdout.columns;
-    const interactivelyWrap = (result: CliCommandResult): CliCommandResult =>
-      process.stderr.isTTY === true && typeof stderrColumns === "number" && result.stderr.length > 0
-        ? { ...result, stderr: wrapLinesForTerminal(result.stderr, stderrColumns) }
-        : result;
-    // Conditionality preserved (the W2 sync seam): an all-local listing
-    // stays a synchronous value wrapped synchronously; only the remote
-    // branch's promise goes through .then.
+    // interactive stderr, so piped runs stay progress-silent. stderr
+    // footnotes stay raw single lines in every mode — wrapping is the
+    // terminal's business (channel philosophy, docs/spec list-command).
     const result = executeListCommand(args.slice(1), {
       currentDirectory,
       registryPath,
@@ -443,11 +415,7 @@ export function runCli(
         : {}),
       emitStdout: (line: string) => stdout(line),
     });
-    return writeCommandResultMaybeAsync(
-      result instanceof Promise ? result.then(interactivelyWrap) : interactivelyWrap(result),
-      stdout,
-      stderr,
-    );
+    return writeCommandResultMaybeAsync(result, stdout, stderr);
   }
 
   if (command === "nav") {

package/src/commands/guide-content/client.txt

@@ -4,16 +4,24 @@ Goal: use registered Services from a workspace by default, without naming an end
 
 Model:
 - Client path is separate from the provider path: it uses Services; it does not declare one.
-- A folder may hold both roles at once (dual-role): a Service folder may also carry its own .ukp/client.toml to set its default scope. Each file is read independently.
+- A folder may hold both roles at once (dual-role): a Service folder may also carry its own .ukp/client.toml to set its default scope. Each file is read independently; 'ukp use' never touches the Service face.
 - A workspace .ukp/client.toml default_endpoints list selects which registered endpoints you mean when no selector is given.
 - UKP walks up from the current directory to find the nearest .ukp/client.toml.
 - Client Config stores endpoint names only; bindings live in the Host Registry.
 - Explicit --endpoint <name> or -g overrides the client defaults. With no Client Config, most commands fall back to every registered endpoint.
 - ukp update is stricter: it does not fall back to the Registry. It uses your Client Config defaults, or requires --endpoint <name> / -g.
-- ukp register does not edit .ukp/client.toml.
-
-1. Create a workspace Client Config
-   .ukp/client.toml at the workspace root:
+- ukp register does not edit .ukp/client.toml; 'ukp use' is the one-step writer.
+
+1. Set the workspace defaults (one step)
+   ukp use endpoint-a endpoint-b
+   Writes .ukp/client.toml (default_endpoints = the names you gave, explicit
+   replace, idempotent) and makes it version-visible in the same step:
+   .ukp/.gitignore ignores machine-local state only (the instance
+   identity), so client.toml and service.toml can be committed. Existing
+   repos carrying the retired '*' template are migrated off it (a local
+   'ukp register' does the same on the service side); operator-owned
+   ignore files are left untouched.
+   Manual form: .ukp/client.toml with
    default_endpoints = ["endpoint-a", "endpoint-b"]
    Each name must match a registered endpoint; run 'ukp list' to see what is registered.
 
@@ -41,8 +49,13 @@ Model:
 
 Remember:
 - Client path consumes Services; provider path (ukp guide service) creates them.
-- Client Config lists names, not paths or provider details.
+- Client Config lists names, not paths or provider details; 'ukp use' is the one-step writer (register still does not edit it).
 - Explicit selectors always beat Client Config defaults.
 - Register does not edit Client Config, and Client Config does not register endpoints.
+- Declarations (client.toml, service.toml) are committable by design; only
+  machine-local state (.ukp/instance-uid) stays ignored - the serve TLS
+  identity lives beside the host registry (~/.ukp/tls/), never in the
+  folder. Commit the config so a fresh clone restores the workspace scope
+  once endpoints are registered.
 - Search run artifacts live outside your folders: %LOCALAPPDATA%\ukp\artifacts
   on Windows, ~/.cache/ukp/artifacts (or $XDG_CACHE_HOME) elsewhere.

package/src/commands/guide-content/remote.txt

@@ -41,6 +41,27 @@ LAN HTTPS path:
    ukp read --endpoint <name> notes/x.md
    ukp rg "keyword" --endpoint <name>
 
+Scoped keys for a second machine or an agent (instead of sharing the env token):
+1. On the host, issue a labeled key (run WITHOUT UKP_SERVE_TOKEN set - while the
+   env token is set it takes precedence and the key file is not consulted)
+   ukp serve token add liku "notes:ro,cad:rw"    # prints the raw key ONCE
+   The key lands in ~/.ukp/tokens (0600, hash-only); scopes are name:ro|rw,
+   comma-separated (full power is the explicit '*:rw'); several keys may share
+   a label for zero-downtime rotation.
+
+2. Serve the door with no env token (the file arms the gate; it is re-read on
+   every request)
+   ukp serve --host 0.0.0.0 --tls
+
+3. On the consuming machine, register with the raw key as the token
+   ukp register --url https://<ip>:8570 --token <raw-key>
+   A scoped key only sees its own endpoints: out-of-scope names answer exactly
+   like nonexistent ones; a read-only scope has no propose route.
+
+4. Revoke on the host (effective on the next request - no restart)
+   ukp serve token list
+   ukp serve token revoke liku
+
 Single endpoint mode:
 Use this when you deliberately want to expose only one endpoint instead of the whole host Registry.
    UKP_SERVE_TOKEN=<token> ukp serve --endpoint <name> --host 0.0.0.0 --tls

package/src/commands/guide-content/rg.txt

@@ -27,8 +27,8 @@ Model:
 
 4. Visibility (every rg mode)
    Hidden files (dot-prefixed, including the .ukp/ wiring) are skipped by
-   default. Add -- --hidden after '--' to include them; -uu also lifts
-   .gitignore rules. 'ukp read' can address hidden files directly either way.
+   default. Add -- --hidden after '--' to include them; --no-ignore also
+   lifts .gitignore rules. 'ukp read' can address hidden files directly either way.
 
 Remember:
 - Exact flags and the passthrough allowlist live in 'ukp rg --help'.

package/src/commands/init.ts

@@ -1,4 +1,4 @@
-import { existsSync, mkdirSync, openSync, closeSync, writeFileSync, unlinkSync, realpathSync, statSync } from "node:fs";
+import { existsSync, mkdirSync, openSync, closeSync, writeFileSync, unlinkSync, readFileSync, readdirSync, renameSync, realpathSync, statSync } from "node:fs";
 import { basename, join } from "node:path";
 import { stringify } from "smol-toml";
 import { ENDPOINT_NAME, loadManifest, type ManifestDependency } from "../config/manifest.ts";
@@ -139,20 +139,231 @@ 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 = [
+/** Precise self-ignore template for `.ukp/` (2026-10-28, inbox
+ * client-portability-and-skill-coverage adoption; `/tls/` line retired
+ * 2026-11-01 by the inbox service-dir-layering adjudication item 2): the
+ * tool-owned directory holds exactly two declaration files
+ * (`service.toml`, `client.toml` — pure declarations with zero machine
+ * paths, versionable by design: a fresh clone re-registers the Service
+ * with one `ukp register`) plus the machine-local state named below.
+ * Ignoring by name keeps identity out of version control and folder sync
+ * (the O-020 B-b goal) while declarations ride with the repo — the `*`
+ * blanket it replaces swallowed them (workflow-lab migration evidence:
+ * the endpoint declaration did not travel with the clone, and carving
+ * client.toml back into tracking cost three fiddly steps). The serve TLS
+ * identity no longer lives here (see UKP_SELF_IGNORE_WITH_TLS). */
+export const UKP_SELF_IGNORE = [
+  "# UKP machine-local state (instance identity) only;",
+  "# declarations (service.toml, client.toml) are versionable by design.",
+  "/instance-uid",
+  "",
+].join("\n");
+
+/** The 2026-10-28 template's first form, retired 2026-11-01 when the
+ * serve TLS identity moved to the machine home (`~/.ukp/tls/<name>/`,
+ * inbox service-dir-layering item 2): its `/tls/` rule named a resident
+ * that no longer exists. Kept verbatim for two recognitions — the posture
+ * ladder classifies it "current" (it IS precise, and a folder that still
+ * carries its legacy `tls/` dir stays correctly ignored until the
+ * serve-side migration moves the material out), and the serve migration
+ * (`retireTlsIgnoreLine`) swaps it onto the current template in the same
+ * gesture that removes the directory. */
+export const UKP_SELF_IGNORE_WITH_TLS = [
+  "# UKP machine-local state (instance identity, TLS key material) only;",
+  "# declarations (service.toml, client.toml) are versionable by design.",
+  "/instance-uid",
+  "/tls/",
+  "",
+].join("\n");
+
+/** The superseded 2026-09-23 `*` template (the original O-020 B-b
+ * landing), kept verbatim for recognition: the posture step below migrates
+ * a `.ukp/.gitignore` that still carries it onto the precise template;
+ * anything else is operator-owned and stays untouched (the B-b
+ * operator-policy-wins posture). */
+export const LEGACY_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");
 
+/** Closed resident set of `.ukp/` (INV-21, owner ruling 2026-11-02): the
+ * declarations, the instance identity, the ignore guard — plus the two
+ * atomic-write transients a crash can leave behind (documented as
+ * "overwritten by the next write"; tolerating them is not an ignore rule,
+ * it is the tool owning its own residue). Anything else is a violation
+ * the posture step refuses on. The serve TLS identity left this directory
+ * on 2026-11-01 (ADR-REM-012), which is exactly why the set is closed:
+ * the template no longer carries defensive rules for residents that
+ * must not exist. */
+const UKP_RESIDENTS: ReadonlySet<string> = new Set([
+  "service.toml",
+  "client.toml",
+  "instance-uid",
+  ".gitignore",
+  ".gitignore.ukp-tmp",
+  "client.toml.ukp-tmp",
+]);
+
+/** Refusal of a posture step over a `.ukp/` holding entries outside the
+ * closed set. Carries the offending paths so every carrier gesture can
+ * print the same operator-facing body. */
+export class UkpResidentError extends Error {
+  constructor(
+    readonly ukpDirectory: string,
+    readonly residents: readonly string[],
+    endpointName?: string,
+  ) {
+    const home = `~/.ukp/tls/${endpointName ?? "<endpoint-name>"}/`;
+    const hasTls = residents.includes("tls");
+    const others = residents.filter((name) => name !== "tls");
+    const lines = [
+      ".ukp/ holds entries UKP does not own (INV-21: service.toml, client.toml, instance-uid and .gitignore only):",
+      ...residents.map((name) => `  ${join(ukpDirectory, name)}`),
+      ...(hasTls
+        ? [`tls/ is a pre-2026-11-01 serve TLS identity: move its cert.pem and key.pem to ${home} to keep the pin clients hold, or delete it.`]
+        : []),
+      ...(others.length > 0 ? [`Delete ${hasTls ? "the rest" : "them"}.`] : []),
+      "The version-control step is refused until .ukp/ is clean - rewriting the ignore guard over material it no longer covers is how a private key becomes committable.",
+    ];
+    super(lines.join("\n"));
+    this.name = "UkpResidentError";
+  }
+}
+
+/** INV-21 admission gate of every posture step (init / use / register):
+ * enumerate `.ukp/` and refuse on any entry outside the closed resident
+ * set. Runs BEFORE any write of the carrying gesture — the template
+ * rewrite most of all. The 2026-11-02 KB incident was a `*` guard swapped
+ * onto the current template while a legacy `tls/` still sat beneath it:
+ * key.pem became addable. Disposition is the owner's (delete, or move the
+ * identity to its machine home); nothing migrates here (key material
+ * relocation is serve's lifecycle), nothing is ignored, no tombstone rule
+ * is written. A missing `.ukp/` passes (nothing to inspect). */
+export function assertUkpResidents(ukpDirectory: string, options: { endpointName?: string } = {}): void {
+  let entries: string[];
+  try {
+    entries = readdirSync(ukpDirectory);
+  } catch (error) {
+    if (error instanceof Error && (error as NodeJS.ErrnoException).code === "ENOENT") return;
+    throw error;
+  }
+  const strangers = entries.filter((name) => !UKP_RESIDENTS.has(name)).sort();
+  if (strangers.length === 0) return;
+  throw new UkpResidentError(ukpDirectory, strangers, options.endpointName);
+}
+
+/** Posture of `.ukp/.gitignore` after a version-control step ran. Two
+ * gestures carry the declarations' version visibility and share this
+ * ladder: `ukp use` (client face) and `ukp register`'s local path (service
+ * face — the service-side touchpoint pure Service folders were missing
+ * until 2026-11-01; they have no reason to run `use`, and re-running
+ * `init service` is refused once the manifest exists). */
+export type UkpIgnorePosture =
+  | "created"
+  | "migrated"
+  /** The 2026-10-28 first precise form (WITH_TLS) swapped onto the current
+   * template: its `/tls/` rule named a resident INV-21 now guarantees
+   * absent — safe to drop only because the admission gate ran first. */
+  | "refreshed"
+  | "current"
+  | "operator-owned"
+  /** Operator-owned AND still carries a bare `*` rule — the declarations
+   * stay invisible; surfaced as a stderr warning with the remedy. */
+  | "operator-owned-star";
+
+/** Same-file template swap through a temp + rename: a concurrent reader
+ * sees either template, never a torn file. */
+function swapUkpIgnoreTemplate(ukpDirectory: string): void {
+  const tempPath = join(ukpDirectory, ".gitignore.ukp-tmp");
+  writeFileSync(tempPath, UKP_SELF_IGNORE, "utf8");
+  renameSync(tempPath, join(ukpDirectory, ".gitignore"));
+}
+
+/** Bring `.ukp/.gitignore` to the precise-ignore posture (the version
+ * control half of `ukp use` and register's local path): create when absent,
+ * migrate a verbatim legacy `*` template, refresh the retired first precise
+ * form, leave anything else untouched — the O-020 B-b operator-policy-wins
+ * rule. The `*` detector is advisory only (a note, never a rewrite). The
+ * INV-21 gate runs here too, so the rewrite itself can never land over
+ * foreign residents even if a carrier forgot to pre-gate (carriers still
+ * pre-gate before their own writes so the whole gesture fails atomically). */
+export function ensureVersionVisibleUkpIgnore(ukpDirectory: string): UkpIgnorePosture {
+  assertUkpResidents(ukpDirectory);
+  const gitignorePath = join(ukpDirectory, ".gitignore");
+  const classify = (): UkpIgnorePosture => {
+    const content = readFileSync(gitignorePath, "utf8");
+    if (content === UKP_SELF_IGNORE) return "current";
+    if (content === LEGACY_UKP_SELF_IGNORE) {
+      swapUkpIgnoreTemplate(ukpDirectory);
+      return "migrated";
+    }
+    if (content === UKP_SELF_IGNORE_WITH_TLS) {
+      swapUkpIgnoreTemplate(ukpDirectory);
+      return "refreshed";
+    }
+    return content.split("\n").some((line) => line.trim() === "*")
+      ? "operator-owned-star"
+      : "operator-owned";
+  };
+  if (!existsSync(gitignorePath)) {
+    try {
+      writeFileSync(gitignorePath, UKP_SELF_IGNORE, { flag: "wx", mode: 0o644 });
+      return "created";
+    } catch (error) {
+      // Concurrent writer installed a guard — classify whatever landed.
+      if (!(error instanceof Error) || (error as NodeJS.ErrnoException).code !== "EEXIST") throw error;
+    }
+  }
+  return classify();
+}
+
+/** stdout line reporting a posture — shared verbatim by every carrier
+ * gesture so the version-control face reads identically wherever it runs. */
+export function renderUkpIgnorePostureLine(posture: UkpIgnorePosture, ukpDirectory: string): string {
+  switch (posture) {
+    case "created":
+      return `version_control: .ukp/.gitignore created (machine-local state ignored; declarations committable)`;
+    case "migrated":
+      return `version_control: .ukp/.gitignore migrated off the retired '*' template (declarations committable; machine-local state stays ignored)`;
+    case "refreshed":
+      return `version_control: .ukp/.gitignore refreshed (retired tls/ rule dropped; machine-local state stays ignored)`;
+    case "current":
+      return `version_control: .ukp/.gitignore already precise (machine-local state only)`;
+    case "operator-owned":
+      return `version_control: .ukp/.gitignore is operator-owned - left untouched (${join(ukpDirectory, ".gitignore")})`;
+    case "operator-owned-star":
+      return `version_control: .ukp/.gitignore is operator-owned - left untouched (see warning)`;
+  }
+}
+
+/** stderr warning for the operator-owned-star posture: the declarations
+ * stay invisible until the operator narrows the file. */
+export function ukpIgnoreStarWarning(ukpDirectory: string): string {
+  return `warning: ${join(ukpDirectory, ".gitignore")} ignores everything ('*'); declarations stay invisible to version control - narrow it to machine-local state (instance-uid) so they can be committed\n`;
+}
+
+/** Serve-side half of the TLS identity relocation (2026-11-01): once the
+ * legacy `.ukp/tls/` material has moved into the machine home, the
+ * by-then-retired first precise template (whose `/tls/` rule guarded it)
+ * swaps onto the current one — verbatim recognition only, so an
+ * operator-owned file is never touched. The posture ladder performs the
+ * same swap as its `refreshed` state; this entry point exists for serve,
+ * which carries no posture step. Returns whether a swap happened. */
+export function retireTlsIgnoreLine(ukpDirectory: string): boolean {
+  const gitignorePath = join(ukpDirectory, ".gitignore");
+  let content: string;
+  try {
+    content = readFileSync(gitignorePath, "utf8");
+  } catch {
+    return false; // no guard in place — nothing to retire
+  }
+  if (content !== UKP_SELF_IGNORE_WITH_TLS) return false;
+  swapUkpIgnoreTemplate(ukpDirectory);
+  return true;
+}
+
 function ensureUkpSelfIgnore(ukpDirectory: string): void {
   const gitignorePath = join(ukpDirectory, ".gitignore");
   if (existsSync(gitignorePath)) return;
@@ -172,6 +383,10 @@ function createServiceManifest(
   const ukpDirectory = join(folder, ".ukp");
   const manifestPath = join(ukpDirectory, "service.toml");
   const { name, nameSource, dependencies } = validateInitServiceOptions(folder, options);
+  // INV-21 admission gate: a pre-existing .ukp/ must hold nothing UKP does
+  // not own before init writes into it — operator-made junk fails loudly
+  // with zero residue (nothing has been written yet).
+  assertUkpResidents(ukpDirectory, { endpointName: name });
   if (existsSync(manifestPath)) {
     throw new Error(`Service Manifest already exists: ${manifestPath}`);
   }