@catheadowl/ukp 0.1.0

package/src/commands/diagnose.ts

@@ -0,0 +1,383 @@
+import { loadManifest, type LoadedManifest, type ManifestCapability } from "../config/manifest.ts";
+import { FILE_NATIVE_CAPABILITIES, isFileNativeCapability } from "../config/file-native.ts";
+import { EXTERNAL_TOOL_CAPABILITIES, EXTERNAL_PROVIDER, isExternalToolCapability } from "../config/external-tool.ts";
+import { isRemoteBinding, localPathOf, readRegistry, type RegistryBinding } from "../registry.ts";
+import { resolveScope } from "../scope.ts";
+import { KitUsageError, parseKitArgs, renderKitHelp, renderKitUsageError, type UkpCommandSpec } from "./kit.ts";
+import { HelpRequestError, isHelpRequest } from "./flags.ts";
+import { defaultQmdCommand } from "../capabilities/qmd.ts";
+import { resolveProposeFolder } from "../capabilities/propose.ts";
+import { rgExecutableAvailable } from "../capabilities/rg.ts";
+
+export interface ProviderCheck {
+  supported: boolean;
+  reason?: string;
+}
+
+export type ProviderResolver = (provider: string, capability?: string) => ProviderCheck;
+
+export interface DiagnoseReport {
+  service: LoadedManifest;
+  capabilities: Array<{
+    name: string;
+    provider: string;
+    source: "manifest" | "derived-local" | "base-tier";
+    status: "ok" | "warning";
+    reason?: string;
+  }>;
+}
+
+export interface DiagnoseCommandContext {
+  currentDirectory: string;
+  registryPath: string;
+  resolveProvider?: ProviderResolver;
+}
+
+export interface DiagnoseCommandResult {
+  exitCode: number;
+  stdout: string;
+  stderr: string;
+}
+
+export interface RenderDiagnoseOptions {
+  includeSearchabilityHint?: boolean;
+}
+
+const SEARCHABILITY_HINT = "hint: diagnose checks wiring, not indexed content; content is searchable after provider setup (see 'ukp guide service qmd').";
+
+/** Single-source command spec (ADR 0024): summary feeds the root help via
+ * cli.ts; usage feeds the help header and the usage-error line; the scope
+ * family, singleton detection, and help-intent triage live in kit.ts. */
+export const DIAGNOSE_SPEC: UkpCommandSpec = {
+  name: "diagnose",
+  summary: "check a Service or endpoints for wiring problems (manifest, provider setup)",
+  group: "operations",
+  description: "Validate a Service folder or selected registered Service endpoints.",
+  usage: "[--endpoint <name> ... | -g]",
+  scope: {
+    endpointHelp: "validate one registered endpoint; repeat to validate multiple endpoints",
+    globalHelp: "validate every endpoint in the Host Registry; takes no value",
+  },
+  helpSuffix: [
+    "",
+    "Scope:",
+    "  With no --endpoint or -g, diagnose validates the current folder as a",
+    "  Service (Manifest and provider wiring). -g validates every registered",
+    "  endpoint; -g cannot be combined with --endpoint.",
+    "",
+  ].join("\n"),
+};
+
+// Provider registration point for this UKP build: every provider that can
+// back a capability must have its availability check here. Adding a provider
+// means (1) a branch in this resolver and (2) a capability adapter under
+// capabilities/ that the command layer dispatches to.
+export function defaultProviderResolver(provider: string, capability = "search"): ProviderCheck {
+  if (isFileNativeCapability(capability)) {
+    // Only the UKP-native file provider exists for the file-native set;
+    // Manifest load already defaults bare declarations to "file".
+    return provider === "file"
+      ? { supported: true }
+      : {
+          supported: false,
+          reason: `provider '${provider}' is not supported for capability '${capability}' by this UKP build`,
+        };
+  }
+  if (isExternalToolCapability(capability)) {
+    // External-tool base tier (ADR-RG-003): the provider marker is fixed;
+    // availability is the base tool itself, degrading to a warning row.
+    if (provider !== EXTERNAL_PROVIDER) {
+      return { supported: false, reason: `provider '${provider}' is not supported for capability '${capability}' by this UKP build` };
+    }
+    return rgExecutableAvailable()
+      ? { supported: true }
+      : { supported: false, reason: "rg executable is not available" };
+  }
+  if (capability === "update") {
+    if (provider !== "qmd") {
+      return { supported: false, reason: `provider '${provider}' is not supported for capability 'update' by this UKP build` };
+    }
+    return defaultQmdCommand()
+      ? { supported: true }
+      : { supported: false, reason: "qmd executable is not available" };
+  }
+  if (capability !== "search") {
+    return { supported: false, reason: `capability '${capability}' is not implemented by this UKP build` };
+  }
+  if (provider !== "qmd") {
+    return { supported: false, reason: `provider '${provider}' is not supported by this UKP build` };
+  }
+  return defaultQmdCommand()
+    ? { supported: true }
+    : { supported: false, reason: "qmd executable is not available" };
+}
+
+function proposeFolderError(serviceFolder: string, declaration: ManifestCapability): string | undefined {
+  try {
+    resolveProposeFolder(serviceFolder, declaration);
+    return undefined;
+  } catch (error) {
+    return error instanceof Error ? error.message : String(error);
+  }
+}
+
+export function evaluateServiceCapabilities(
+  service: LoadedManifest,
+  resolveProvider: ProviderResolver = defaultProviderResolver,
+): DiagnoseReport["capabilities"] {
+  const manifestCapabilities = Object.entries(service.manifest.capabilities).map(([name, declaration]) => {
+    // Provider is guaranteed post-load for valid Manifests (file-native bare
+    // declarations default to "file"; others fail at load). The "(none)"
+    // arm is defensive depth for direct API callers.
+    const provider = declaration.provider ?? "(none)";
+    const check = resolveProvider(provider, name);
+    // Front-load propose folder validation so config typos surface in the
+    // Service-side self-check instead of the first `ukp propose` run.
+    const folderError = name === "propose"
+      ? proposeFolderError(service.folder, declaration)
+      : undefined;
+    const supported = check.supported && folderError === undefined;
+    const reason = !check.supported ? check.reason : folderError;
+    return {
+      name,
+      provider,
+      source: "manifest" as const,
+      status: supported ? "ok" as const : "warning" as const,
+      ...(reason ? { reason } : {}),
+    };
+  });
+
+  // Derived file-native defaults (ADR 0016 rule 2): every read-side
+  // file-native capability not declared by the Manifest is still effectively
+  // present. The table is the single source — no per-capability rows here.
+  const derived = Object.entries(FILE_NATIVE_CAPABILITIES)
+    .filter(([name, spec]) => spec.derived && !Object.hasOwn(service.manifest.capabilities, name))
+    .map(([name]) => {
+      const check = resolveProvider("file", name);
+      return {
+        name,
+        provider: "file",
+        source: "derived-local" as const,
+        status: check.supported ? "ok" as const : "warning" as const,
+        ...(check.reason ? { reason: check.reason } : {}),
+      };
+    });
+
+  // External-tool base tier (ADR-RG-003): base-tier members are effectively
+  // present on every registered local Service without declaration; a missing
+  // base tool degrades the row to a warning, never hides it.
+  const baseTier = Object.entries(EXTERNAL_TOOL_CAPABILITIES)
+    .filter(([name, spec]) => spec.baseTier && !Object.hasOwn(service.manifest.capabilities, name))
+    .map(([name]) => {
+      const check = resolveProvider(EXTERNAL_PROVIDER, name);
+      return {
+        name,
+        provider: EXTERNAL_PROVIDER,
+        source: "base-tier" as const,
+        status: check.supported ? "ok" as const : "warning" as const,
+        ...(check.reason ? { reason: check.reason } : {}),
+      };
+    });
+  return [...manifestCapabilities, ...derived, ...baseTier];
+}
+
+export function diagnoseService(
+  serviceFolder: string,
+  resolveProvider: ProviderResolver = defaultProviderResolver,
+): DiagnoseReport {
+  const service = loadManifest(serviceFolder);
+  const capabilities = evaluateServiceCapabilities(service, resolveProvider);
+
+  if (!capabilities.some((capability) => capability.status === "ok")) {
+    throw new Error("NO_SUPPORTED_CAPABILITY");
+  }
+  return { service, capabilities };
+}
+
+export function renderDependencyRegistryWarnings(
+  service: LoadedManifest,
+  registry: readonly RegistryBinding[],
+): string[] {
+  if (!service.manifest.dependencies || service.manifest.dependencies.length === 0) return [];
+  const registeredEndpoints = new Set(registry.map((binding) => binding.name));
+  return service.manifest.dependencies
+    .filter((dependency) => !registeredEndpoints.has(dependency.endpoint))
+    .map((dependency) =>
+      `dependency target '${dependency.endpoint}' is not registered (declared by ${service.effectiveName})`
+    );
+}
+
+function parseDiagnoseArgs(args: readonly string[]): {
+  explicitEndpoints?: string[];
+  global: boolean;
+  warnings: string[];
+} {
+  const parsed = parseKitArgs(DIAGNOSE_SPEC, args);
+  return {
+    explicitEndpoints: parsed.scope.explicitEndpoints,
+    global: parsed.scope.global,
+    warnings: parsed.scope.warnings,
+  };
+}
+
+function diagnoseBinding(
+  binding: RegistryBinding,
+  resolveProvider: ProviderResolver | undefined,
+): { status: "ok"; report: DiagnoseReport } | { status: "failed"; message: string } {
+  if (isRemoteBinding(binding)) {
+    return {
+      status: "failed",
+      message: `remote endpoint '${binding.name}' (${binding.url}): diagnose is local-only in ukp_remote W2; reachability shows in 'ukp list'`,
+    };
+  }
+  try {
+    const report = diagnoseService(localPathOf(binding), resolveProvider);
+    if (report.service.effectiveName !== binding.name) {
+      return {
+        status: "failed",
+        message: `endpoint '${binding.name}' no longer matches Service effective name '${report.service.effectiveName}'`,
+      };
+    }
+    return { status: "ok", report };
+  } catch (error) {
+    return { status: "failed", message: error instanceof Error ? error.message : String(error) };
+  }
+}
+
+export function executeDiagnoseCommand(
+  args: readonly string[],
+  context: DiagnoseCommandContext,
+): DiagnoseCommandResult {
+  if (isHelpRequest(args)) {
+    return { exitCode: 0, stdout: renderDiagnoseHelp(), stderr: "" };
+  }
+
+  try {
+    const parsed = parseDiagnoseArgs(args);
+    if (!parsed.explicitEndpoints && !parsed.global) {
+      try {
+        const report = diagnoseService(context.currentDirectory, context.resolveProvider);
+        let dependencyWarnings: string[] = [];
+        try {
+          dependencyWarnings = renderDependencyRegistryWarnings(report.service, readRegistry(context.registryPath));
+        } catch (error) {
+          if (report.service.manifest.dependencies && report.service.manifest.dependencies.length > 0) {
+            dependencyWarnings = [
+              `dependency registry check skipped: ${error instanceof Error ? error.message : String(error)}`,
+            ];
+          }
+        }
+        const warnings = [...parsed.warnings, ...dependencyWarnings];
+        return {
+          exitCode: 0,
+          stdout: renderDiagnose(report, {
+            includeSearchabilityHint: true,
+          }),
+          stderr: warnings.length > 0 ? `${warnings.join("\n")}\n` : "",
+        };
+      } catch (error) {
+        return {
+          exitCode: 1,
+          stdout: "",
+          stderr: renderLocalDiagnoseError(error instanceof Error ? error.message : String(error)),
+        };
+      }
+    }
+
+    const registry = readRegistry(context.registryPath);
+    const scope = resolveScope({
+      currentDirectory: context.currentDirectory,
+      registry,
+      explicitEndpoints: parsed.explicitEndpoints,
+      global: parsed.global,
+    });
+    const warnings = [...parsed.warnings, ...scope.warnings];
+    const output: string[] = [];
+    let failed = false;
+
+    for (const binding of scope.bindings) {
+      output.push(`== ${binding.name} ==`);
+      const result = diagnoseBinding(binding, context.resolveProvider);
+      if (result.status === "ok") {
+        output.push(renderDiagnose(result.report, { includeSearchabilityHint: true }).trimEnd());
+        warnings.push(...renderDependencyRegistryWarnings(result.report.service, registry));
+      } else {
+        failed = true;
+        output.push("status: failed");
+        output.push(`error: ${result.message}`);
+      }
+    }
+
+    if (scope.bindings.length === 0) {
+      failed = true;
+      warnings.push("no endpoints selected: the Host Registry is empty; run 'ukp register' from a Service folder, then retry");
+    }
+
+    return {
+      exitCode: failed ? 1 : 0,
+      stdout: output.length > 0 ? `${output.join("\n")}\n` : "",
+      stderr: warnings.length > 0 ? `${warnings.join("\n")}\n` : "",
+    };
+  } catch (error) {
+    if (error instanceof HelpRequestError) {
+      return { exitCode: 0, stdout: renderDiagnoseHelp(), stderr: "" };
+    }
+    if (error instanceof KitUsageError) {
+      return { exitCode: 2, stdout: "", stderr: renderDiagnoseUsageError(error.message) };
+    }
+    return {
+      exitCode: 1,
+      stdout: "",
+      stderr: `ukp diagnose: ${error instanceof Error ? error.message : String(error)}\n`,
+    };
+  }
+}
+
+export function renderLocalDiagnoseError(message: string): string {
+  return [
+    `ukp diagnose: ${message}`,
+    "Hint: 'ukp diagnose' checks the current folder as a Service.",
+    "Run 'ukp guide service' for the short onboarding guide.",
+    "Use 'ukp diagnose -g' to validate every registered endpoint, or 'ukp diagnose --endpoint <name>' for one endpoint.",
+  ].join("\n") + "\n";
+}
+
+export function renderDiagnose(report: DiagnoseReport, options: RenderDiagnoseOptions = {}): string {
+  const lines = [
+    `endpoint: ${report.service.effectiveName} (source: ${report.service.nameSource})`,
+  ];
+  if (report.service.manifest.description) {
+    lines.push(`description: ${report.service.manifest.description}`);
+  }
+  if (report.service.manifest.dependencies && report.service.manifest.dependencies.length > 0) {
+    for (const dependency of report.service.manifest.dependencies) {
+      lines.push(`dependency: depends_on -> ${dependency.endpoint} (kind: ${dependency.kind})`);
+      if (dependency.reason) {
+        lines.push(`dependency_reason: ${dependency.reason}`);
+      }
+    }
+  }
+  lines.push(`location: ${report.service.folder}`);
+  const showSearchabilityHint = options.includeSearchabilityHint
+    && report.capabilities.some((capability) => capability.name === "search" && capability.status === "ok");
+  for (const capability of report.capabilities) {
+    lines.push(capability.source === "derived-local"
+      ? `capability: ${capability.name} (derived local baseline)`
+      : capability.source === "base-tier"
+        ? `capability: ${capability.name} (external-tool base tier)`
+        : `capability: ${capability.name}`);
+    lines.push(`provider: ${capability.provider}`);
+    lines.push(`status: ${capability.status}`);
+    if (capability.reason) lines.push(`warning: ${capability.reason}`);
+  }
+  if (showSearchabilityHint) lines.push(SEARCHABILITY_HINT);
+  return `${lines.join("\n")}\n`;
+}
+
+export function renderDiagnoseHelp(): string {
+  return renderKitHelp(DIAGNOSE_SPEC);
+}
+
+export function renderDiagnoseUsageError(message: string): string {
+  return renderKitUsageError(DIAGNOSE_SPEC, message);
+}

package/src/commands/flags.ts

@@ -0,0 +1,49 @@
+import { CommanderError } from "commander";
+
+export function countFlagOccurrences(args: readonly string[], flag: string): number {
+  if (flag.startsWith("--")) {
+    return args.filter((argument) => argument === flag || argument.startsWith(`${flag}=`)).length;
+  }
+
+  if (!flag.startsWith("-") || flag.length !== 2) {
+    return args.filter((argument) => argument === flag).length;
+  }
+
+  const shortFlag = flag[1];
+  return args.reduce((count, argument) => {
+    if (argument === flag) return count + 1;
+    if (!argument.startsWith("-") || argument.length <= 2) return count;
+
+    const bundle = argument.slice(1);
+    if (!/^[A-Za-z]+$/.test(bundle)) return count;
+    if (!bundle.split("").every((character) => character === shortFlag)) return count;
+    return count + bundle.length;
+  }, 0);
+}
+
+export function isHelpRequest(args: readonly string[]): boolean {
+  return args.length === 1 && (args[0] === "-h" || args[0] === "--help");
+}
+
+/** commander reports help/version intent through exitOverride's
+ * CommanderError (codes `commander.help` / `commander.helpDisplayed` /
+ * `commander.version`); the `(outputHelp)` message is an internal sentinel,
+ * not user-facing text. Options are order-independent, so `--help` must win
+ * wherever it appears, and the parse layer must not translate these into
+ * usage errors. Call inside an `instanceof CommanderError` guard — a type
+ * predicate here would narrow the sibling branch to `never`. */
+export function isCommanderHelpIntent(error: CommanderError): boolean {
+  return error.code === "commander.help"
+    || error.code === "commander.helpDisplayed"
+    || error.code === "commander.version";
+}
+
+/** Flows from the parse layer (whose configureOutput silencing swallowed
+ * commander's own help rendering) to the execute layer, which re-renders
+ * help and returns exit 0. */
+export class HelpRequestError extends Error {
+  constructor() {
+    super("help requested");
+    this.name = "HelpRequestError";
+  }
+}

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

@@ -0,0 +1,36 @@
+UKP Client quickstart
+
+Goal: use registered Services from a workspace by default, without naming an endpoint on every call.
+
+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 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:
+   default_endpoints = ["endpoint-a", "endpoint-b"]
+   Each name must match a registered endpoint; run 'ukp list' to see what is registered.
+
+2. Use Services without a selector
+   ukp search "keyword"
+   ukp inspect
+   ukp read --endpoint endpoint-a docs/example.md   (read still names a path, and --endpoint here wins)
+
+3. Check which scope is active
+   ukp inspect
+   It prints scope: explicit / global / client-config / registry-fallback and the source.
+
+4. Dangling defaults warn instead of failing silently
+   A default_endpoints entry not registered yet is reported as a warning by inspect, and commands still run on the resolvable ones.
+
+Remember:
+- Client path consumes Services; provider path (ukp guide service) creates them.
+- Client Config lists names, not paths or provider details.
+- Explicit selectors always beat Client Config defaults.
+- Register does not edit Client Config, and Client Config does not register endpoints.

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

@@ -0,0 +1,38 @@
+UKP propose quickstart
+
+Goal: submit a change proposal to a Service endpoint as an idempotent, adjudicable document — not a file write.
+
+Model:
+- A proposal is a pending change the Service owner will adjudicate; the submitter proposes, the owner decides.
+- Identity is client-owned: you pick the id (a slug), and resubmitting the same id updates the same proposal.
+- Submission is an upsert with three outcomes: created (new, revision 1), unchanged (identical content, no write), updated (replaced, revision +1).
+- revision is an audit counter and the history of your edits; it never resets.
+- ukp propose is the only documented write path. Never edit Service-side proposal files directly: a later submission overwrites them and your edits bypass revision tracking.
+
+1. Declare the capability (Service side)
+   .ukp/service.toml:
+   [capabilities.propose]
+   provider = "file"
+   The provider line is optional (a bare [capabilities.propose] means the file provider).
+   Optional [capabilities.propose.config] folder = "inbox" (default) sets where proposals land.
+
+2. Submit a proposal
+   ukp propose --endpoint <name> --file draft.md
+   --id defaults to the draft basename (extension stripped); the basename becomes the proposal's persistent identity.
+   Renaming the file and resubmitting creates a new proposal, not a revision.
+   Pass --id <slug> to pin the identity explicitly.
+   Add --json for a machine-readable envelope (id, status, revision).
+
+3. Revise a proposal
+   Edit your local draft, then run the same command with the same id.
+   The Service replaces the stored proposal, keeps created, bumps revision, refreshes updated.
+   Identical resubmission is a no-op (exit 0, revision unchanged).
+
+4. Read proposals back
+   Reading is owned by the Service: if it indexes its proposal folder into its search surface,
+   ukp search / ukp read reach proposals like any other content.
+
+Remember:
+- Same id, same proposal: do not fork ids (add-topic, add-topic-v2) for revisions of one idea.
+- Frontmatter service fields (id, status, revision, created, updated) are Service-maintained and stripped from submissions; your subject/kind display fields pass through.
+- status stays "proposed" until adjudication exists; there is no accept/reject command yet.

package/src/commands/guide-content/service-qmd.txt

@@ -0,0 +1,44 @@
+UKP Service quickstart - QMD provider setup
+
+Goal: make a registered Service's content searchable through the default QMD provider.
+Run these from the Service folder root.
+
+Boundary:
+- These are provider-owned steps. QMD owns collection, index, ranking, and config.
+- UKP only routes capability requests. This topic carries the journey; exact
+  flags and arguments belong to the relevant QMD subcommand help.
+
+Fast path for a simple knowledge folder:
+1. qmd init
+2. qmd collection add .
+3. qmd update
+4. qmd search "keyword"
+5. qmd get <reference> --no-line-numbers
+
+1. Initialize QMD (qmd init)
+2. Add the searchable collections (qmd collection add)
+   For a pure knowledge base, add the folder root; otherwise add the folder(s)
+   whose content should be searchable.
+3. Use a stable short collection name (qmd collection rename)
+   QMD names a collection from the indexed folder; rename it to a short
+   stable name so provider-native artifact URIs stay clean.
+4. Update the index (qmd update, qmd status)
+5. Verify the provider before returning to UKP (qmd search / qmd get)
+   If a search returns matches, the provider is ready; return to
+   'ukp guide service' step 4.
+   A read smoke ('qmd get <reference> --no-line-numbers') is required for
+   observe mode (external or nested collection root): it confirms the provider
+   can resolve the provider references that ukp read will delegate to it
+   (bare docid handoff keys and qmd:// references).
+
+Exact flags and arguments come from the relevant QMD subcommand help, for example:
+  qmd init --help
+  qmd collection add --help
+  qmd update --help
+  qmd search --help
+  qmd get --help
+
+Remember:
+- Provider config is not stored in the UKP Registry.
+- A registered Service is addressable; it is searchable only after provider setup.
+- Keep the local index out of version control: ignore .qmd/*.sqlite and .qmd/*.sqlite-*.

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

@@ -0,0 +1,114 @@
+UKP Service quickstart
+
+Goal: make a folder a named Knowledge Service, register it, inspect the route, search it, and read an endpoint-scoped reference.
+Run the setup commands from the Service folder root.
+
+Fast path:
+1. Create the UKP Service Manifest
+   ukp init service --name your-endpoint-name
+   Optional: add --description "Short boundary note"
+
+2. Make content searchable through the provider
+   ukp guide service qmd
+
+3. Validate and register the Service
+   ukp diagnose
+   ukp register
+   ukp list
+
+4. Inspect, search, then read
+   ukp inspect --endpoint your-endpoint-name
+   ukp search "keyword" --endpoint your-endpoint-name --limit 3
+   ukp read --endpoint your-endpoint-name <reference>
+
+Key boundary:
+- init/register makes the folder addressable as a Service.
+- provider setup makes the Service's content searchable.
+- Both are needed for an end-to-end search path.
+
+Model:
+- A UKP Service is a knowledge endpoint that declares capabilities.
+- Four separate journeys:
+  - provider path: init service + register make a folder an addressable Service;
+  - content-searchable: provider setup decides what content is indexed (provider-owned; see 'ukp guide service qmd');
+  - declared dependencies: a Service Manifest can declare [[dependencies]] entries with endpoint + kind; this is declarative only;
+  - client path: a workspace .ukp/client.toml default scope lets you use Services by default instead of naming one each call.
+- Registered as a Service does not mean its content is searchable; both steps are needed.
+- QMD is the current default search/update provider, not the definition of a Service.
+- Provider setup is provider-owned: the provider owns collection, index, ranking, and config.
+
+Details:
+
+1. Choose a stable Service folder
+   Use the project or knowledge-domain root. Limit searchable subfolders in the provider, not in the UKP Registry.
+
+2. Create the UKP Service Manifest
+   ukp init service --name your-endpoint-name
+   Optional: add --description "Short boundary note"
+   Name must be a lowercase endpoint slug, for example: cad-notes
+   This writes .ukp/service.toml with the current minimal provider declaration:
+   [capabilities.search]
+   provider = "qmd"
+
+3. Make content searchable through the provider (provider-owned)
+   Provider setup is not a UKP step. For the default QMD provider:
+   ukp guide service qmd
+   That topic points exact flags and arguments to the relevant QMD subcommand help.
+
+   If this Service depends on other externally consumed knowledge endpoints,
+   declare them in the Manifest with repeated --dependency <name> entries;
+   each entry becomes [[dependencies]] with kind = "context" and can be edited later.
+
+4. Validate and register
+   ukp diagnose
+   ukp register
+   ukp list
+   At this point the folder is a registered Service: addressable and callable.
+   Its content is searchable only because step 3 configured the provider.
+
+5. Inspect the effective route
+   ukp inspect --endpoint your-endpoint-name
+   Use inspect when you need to explain scope, Registry binding, Manifest capability, or provider availability.
+
+6. Search
+   ukp search "keyword" --endpoint your-endpoint-name --limit 3
+   ukp search "keyword" --endpoint your-endpoint-name --limit 3 --json
+   ukp search "keyword" --endpoint your-endpoint-name --recursive
+   In a workspace with .ukp/client.toml default_endpoints, you can omit --endpoint for search.
+
+7. Read an endpoint-scoped reference
+   Every registered local Service has the derived read/file baseline; no Manifest get entry is needed.
+   ukp read --endpoint your-endpoint-name docs/example.md
+   ukp read --endpoint your-endpoint-name docs/example.md --lines 10:20
+   Search results carry copyable handoff lines you can paste straight into read:
+   - a ukp://<endpoint>/<path> URI is the durable, endpoint-scoped reference;
+   - a bare docid is the provider's short-lived document id (QMD handoff key).
+   On a QMD-backed Service (including observe mode), provider content is read with
+   'ukp read --endpoint <name> <docid handoff key or qmd:// reference>'; do not
+   manually convert qmd:// provider locations into Service-folder paths.
+
+8. Update provider-owned state
+   This is optional for the first search path. Add this capability to .ukp/service.toml when provider maintenance should be exposed:
+   [capabilities.update]
+   provider = "qmd"
+   ukp update --endpoint your-endpoint-name
+   In a workspace with .ukp/client.toml default_endpoints, you can omit --endpoint for update too.
+   Use ukp update -g only when you explicitly want to update every registered endpoint.
+
+Advanced:
+- Declared dependencies belong in the Service Manifest as [[dependencies]] entries.
+- ukp init service --dependency <name> emits a context dependency; edit the Manifest later for authority, implementation, evidence, or a reason.
+- Dependencies do not change ordinary search/read. Only explicit search --recursive traverses direct authority/context dependencies.
+- Workspace defaults belong to the client path; run 'ukp guide client' from the consuming workspace.
+- update is a provider-owned maintenance route, not part of the first search smoke.
+
+Remember:
+- Endpoint name identifies the Service.
+- Host Registry stores endpoint name -> Service folder path.
+- Provider collection decides what content is indexed; folder-external authoritative knowledge should be modeled as its own endpoint when UKP ownership matters.
+- Register makes the folder addressable; it does not make content searchable (provider indexing does).
+- Register does not edit .ukp/client.toml or provider configuration.
+- Declarative dependencies live in the Service Manifest as [[dependencies]] entries; they do not change ordinary search/read, while explicit search --recursive traverses direct authority/context dependencies.
+- Future providers should add provider adapters instead of turning provider internals into UKP rules.
+- To register an already-used name at a new location, unregister the old binding first:
+  ukp unregister --endpoint <name>