@kici-dev/compiler 0.1.15 → 0.1.16

package/dist/commands/held-run-client.js

@@ -0,0 +1,98 @@
+import "../chunk-gOLHoazu.js";
+import { loadGlobalConfig } from "../remote/config.js";
+import pc from "picocolors";
+import { logger } from "@kici-dev/core";
+//#region src/commands/held-run-client.ts
+/**
+* Shared HTTP plumbing for the `kici approve` / `kici reject` held-run
+* commands. Resolves auth + endpoint from the global config (PAT preferred,
+* API key fallback; Platform endpoint preferred, orchestrator fallback) and
+* exposes thin list / approve / reject helpers against the Platform dashboard
+* API.
+*/
+/**
+* Resolve the auth context, printing a clear error and returning null when the
+* CLI is not authenticated / no active org is set.
+*/
+async function resolveHeldRunContext() {
+	const config = await loadGlobalConfig();
+	const token = config.pat ?? config.token;
+	if (!token) {
+		logger.error(pc.red("Not authenticated. Run `kici login` to get started."));
+		return null;
+	}
+	const endpoint = config.platformEndpoint ?? config.endpoint;
+	if (!endpoint) {
+		logger.error(pc.red("No endpoint configured. Run `kici login` to configure."));
+		return null;
+	}
+	if (!config.activeOrgId) {
+		logger.error(pc.red("No active organization. Run `kici org use <name>` to set one."));
+		return null;
+	}
+	return {
+		endpoint,
+		token,
+		orgId: config.activeOrgId
+	};
+}
+function authHeaders(token) {
+	return {
+		"Content-Type": "application/json",
+		Authorization: `Bearer ${token}`
+	};
+}
+/** List the held runs for a single run id. */
+async function listHeldRunsForRun(ctx, runId) {
+	const url = `${ctx.endpoint}/api/v1/orgs/${ctx.orgId}/held-runs?runId=${encodeURIComponent(runId)}`;
+	const response = await fetch(url, {
+		method: "GET",
+		headers: authHeaders(ctx.token)
+	});
+	if (!response.ok) throw new Error(await describeError(response));
+	return (await response.json()).heldRuns ?? [];
+}
+/** POST an approve decision for a held run. Returns true on success. */
+async function postApprove(ctx, heldRunId) {
+	const url = `${ctx.endpoint}/api/v1/orgs/${ctx.orgId}/held-runs/${heldRunId}/approve`;
+	const response = await fetch(url, {
+		method: "POST",
+		headers: authHeaders(ctx.token)
+	});
+	if (!response.ok) {
+		logger.error(pc.red(await describeError(response)));
+		return false;
+	}
+	return true;
+}
+/** POST a reject decision (with reason) for a held run. Returns true on success. */
+async function postReject(ctx, heldRunId, reason) {
+	const url = `${ctx.endpoint}/api/v1/orgs/${ctx.orgId}/held-runs/${heldRunId}/reject`;
+	const response = await fetch(url, {
+		method: "POST",
+		headers: authHeaders(ctx.token),
+		body: JSON.stringify({ reason })
+	});
+	if (!response.ok) {
+		logger.error(pc.red(await describeError(response)));
+		return false;
+	}
+	return true;
+}
+/** Build a user-facing error string from a failed response. */
+async function describeError(response) {
+	let detail;
+	try {
+		detail = (await response.json()).error;
+	} catch {}
+	switch (response.status) {
+		case 401: return "Authentication failed. Run `kici login` to re-authenticate.";
+		case 403: return `Access denied${detail ? `: ${detail}` : ""}.`;
+		case 404: return `Held run not found${detail ? `: ${detail}` : ""}.`;
+		default: return detail ?? `Request failed with status ${response.status}.`;
+	}
+}
+//#endregion
+export { listHeldRunsForRun, postApprove, postReject, resolveHeldRunContext };
+
+//# sourceMappingURL=held-run-client.js.map

package/dist/commands/held-run-resolve.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Shared held-run resolution for the `kici approve` / `kici reject` commands.
+ *
+ * Both commands first list the pending holds for a run, then resolve the one
+ * the user named via `--job` / `--step` (or the sole pending hold when there is
+ * exactly one and no filter is given). The resolution is a pure function so it
+ * can be unit-tested without HTTP.
+ */
+/** Hold scope, mirroring the engine `HoldScope` enum. */
+export type HeldRunScope = 'workflow' | 'job' | 'step';
+/** A pending-hold row as returned by `GET /orgs/:orgId/held-runs`. */
+export interface HeldRunSummary {
+    id: string;
+    runId: string;
+    jobId?: string;
+    holdScope?: HeldRunScope;
+    stepIndex?: number | null;
+    status: string;
+}
+/** Filters supplied on the command line. */
+export interface HeldRunFilter {
+    /** Match a hold by its job name. */
+    job?: string;
+    /** Match a step-scoped hold by its step index (compared as a string). */
+    step?: string;
+}
+/** Resolution result: either a held-run id or a user-facing error message. */
+export type ResolveResult = {
+    ok: true;
+    heldRunId: string;
+    hold: HeldRunSummary;
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * Resolve the held-run id matching the filter from a list of pending holds.
+ *
+ * - `--step` requires `--job` and matches a `step`-scoped hold whose step index
+ *   equals the given value.
+ * - `--job` alone matches a `job`/`workflow`-scoped hold for that job.
+ * - With no filter, the sole pending hold is used; ambiguity is an error.
+ */
+export declare function resolveHeldRunId(holds: readonly HeldRunSummary[], filter: HeldRunFilter): ResolveResult;
+//# sourceMappingURL=held-run-resolve.d.ts.map

package/dist/commands/held-run-resolve.js

@@ -0,0 +1,53 @@
+import "../chunk-gOLHoazu.js";
+//#region src/commands/held-run-resolve.ts
+/**
+* Resolve the held-run id matching the filter from a list of pending holds.
+*
+* - `--step` requires `--job` and matches a `step`-scoped hold whose step index
+*   equals the given value.
+* - `--job` alone matches a `job`/`workflow`-scoped hold for that job.
+* - With no filter, the sole pending hold is used; ambiguity is an error.
+*/
+function resolveHeldRunId(holds, filter) {
+	const pending = holds.filter((h) => h.status === "pending");
+	if (pending.length === 0) return {
+		ok: false,
+		error: "No pending approval holds found for this run."
+	};
+	if (filter.step !== void 0) {
+		if (!filter.job) return {
+			ok: false,
+			error: "--step requires --job to identify the held step."
+		};
+		return pickSingle(pending.filter((h) => h.holdScope === "step" && h.jobId === filter.job && String(h.stepIndex ?? "") === filter.step), `step ${filter.step} of job '${filter.job}'`);
+	}
+	if (filter.job !== void 0) return pickSingle(pending.filter((h) => h.jobId === filter.job && h.holdScope !== "step"), `job '${filter.job}'`);
+	if (pending.length > 1) return {
+		ok: false,
+		error: "Multiple pending holds for this run. Use --job <name> (and --step <index>) to choose one."
+	};
+	return {
+		ok: true,
+		heldRunId: pending[0].id,
+		hold: pending[0]
+	};
+}
+function pickSingle(matches, label) {
+	if (matches.length === 0) return {
+		ok: false,
+		error: `No pending hold found for ${label}.`
+	};
+	if (matches.length > 1) return {
+		ok: false,
+		error: `Multiple pending holds match ${label}; cannot disambiguate.`
+	};
+	return {
+		ok: true,
+		heldRunId: matches[0].id,
+		hold: matches[0]
+	};
+}
+//#endregion
+export { resolveHeldRunId };
+
+//# sourceMappingURL=held-run-resolve.js.map

package/dist/commands/hook.js

@@ -2,9 +2,9 @@ import "../chunk-gOLHoazu.js";
 import { detectHookTools, findGitDir } from "../hooks/detector.js";
 import { installHook } from "../hooks/installer.js";
 import "../hooks/index.js";
+import path from "node:path";
 import pc from "picocolors";
 import { readFile } from "node:fs/promises";
-import path from "node:path";
 import { logger, toErrorMessage } from "@kici-dev/core";
 import { select } from "@inquirer/prompts";
 //#region src/commands/hook.ts

package/dist/commands/index.d.ts

@@ -24,6 +24,10 @@ export { orgListCommand, orgUseCommand, orgCurrentCommand } from './org.js';
 export { logoutCommand } from './logout.js';
 export { cancelCommand } from './cancel.js';
 export type { CancelOptions } from './cancel.js';
+export { approveCommand } from './approve.js';
+export type { ApproveOptions } from './approve.js';
+export { rejectCommand } from './reject.js';
+export type { RejectOptions } from './reject.js';
 export { workflowsListCommand } from './workflows.js';
 export type { WorkflowsListOptions } from './workflows.js';
 export { drainWorkerCommand } from './drain-worker.js';

package/dist/commands/index.js

@@ -1,5 +1,6 @@
 import "../chunk-gOLHoazu.js";
 import { compileCommand } from "./compile.js";
+import { approveCommand } from "./approve.js";
 import { cancelCommand } from "./cancel.js";
 import { docsCommand, docsLlmCommand } from "./docs.js";
 import { drainWorkerCommand } from "./drain-worker.js";
@@ -16,5 +17,6 @@ import { statusCommand } from "./status.js";
 import { typesCommand } from "./types.js";
 import { orgCurrentCommand, orgListCommand, orgUseCommand } from "./org.js";
 import { logoutCommand } from "./logout.js";
+import { rejectCommand } from "./reject.js";
 import { workflowsListCommand } from "./workflows.js";
-export { cancelCommand, compileCommand, docsCommand, docsLlmCommand, drainWorkerCommand, endpointsCommand, fixtureCommand, hookInstallCommand, initCommand, loginCommand, logoutCommand, orgCurrentCommand, orgListCommand, orgUseCommand, runLocalCommand, runRemoteCommand, secretsListCommand, statusCommand, testCommand, testDryRun, typesCommand, watchCommand, workflowsListCommand };
+export { approveCommand, cancelCommand, compileCommand, docsCommand, docsLlmCommand, drainWorkerCommand, endpointsCommand, fixtureCommand, hookInstallCommand, initCommand, loginCommand, logoutCommand, orgCurrentCommand, orgListCommand, orgUseCommand, rejectCommand, runLocalCommand, runRemoteCommand, secretsListCommand, statusCommand, testCommand, testDryRun, typesCommand, watchCommand, workflowsListCommand };

package/dist/commands/init.js

@@ -7,9 +7,9 @@ import { detectHookTools, findGitDir } from "../hooks/detector.js";
 import { installHook } from "../hooks/installer.js";
 import "../hooks/index.js";
 import { getTypeScriptPaths } from "../execution/sdk-alias.js";
+import path from "node:path";
 import pc from "picocolors";
 import { access, mkdir, readFile, rm, writeFile } from "node:fs/promises";
-import path from "node:path";
 import { initZx, logger, toErrorMessage } from "@kici-dev/core";
 import { detectPackageManager, installBuildPolicyArgs, installCommand, parsePackageManager } from "@kici-dev/core/package-manager";
 import { checkbox, confirm, select } from "@inquirer/prompts";

package/dist/commands/reject.d.ts

@@ -0,0 +1,25 @@
+/**
+ * kici reject command
+ *
+ * Rejects a held approval gate for a run (requires `--reason`). Resolves the
+ * held element by `--job` / `--step` (or the sole pending hold), then records
+ * the rejection via the Platform dashboard API (PAT auth).
+ */
+/** Options for the reject command. */
+export interface RejectOptions {
+    /** Match a hold by its job name. */
+    job?: string;
+    /** Match a step-scoped hold by its step index. */
+    step?: string;
+    /** Required rejection reason. */
+    reason?: string;
+}
+/**
+ * Reject a held approval gate.
+ *
+ * @param runId - The run whose hold to reject.
+ * @param options - Job/step filters plus the required reason.
+ * @returns true on success, false on error.
+ */
+export declare function rejectCommand(runId: string, options?: RejectOptions): Promise<boolean>;
+//# sourceMappingURL=reject.d.ts.map

package/dist/commands/reject.js

@@ -0,0 +1,49 @@
+import "../chunk-gOLHoazu.js";
+import { listHeldRunsForRun, postReject, resolveHeldRunContext } from "./held-run-client.js";
+import { resolveHeldRunId } from "./held-run-resolve.js";
+import pc from "picocolors";
+import { logger, toErrorMessage } from "@kici-dev/core";
+//#region src/commands/reject.ts
+/**
+* kici reject command
+*
+* Rejects a held approval gate for a run (requires `--reason`). Resolves the
+* held element by `--job` / `--step` (or the sole pending hold), then records
+* the rejection via the Platform dashboard API (PAT auth).
+*/
+/**
+* Reject a held approval gate.
+*
+* @param runId - The run whose hold to reject.
+* @param options - Job/step filters plus the required reason.
+* @returns true on success, false on error.
+*/
+async function rejectCommand(runId, options = {}) {
+	try {
+		if (!options.reason) {
+			logger.error(pc.red("A rejection reason is required. Pass --reason <text>."));
+			return false;
+		}
+		const ctx = await resolveHeldRunContext();
+		if (!ctx) return false;
+		const resolution = resolveHeldRunId(await listHeldRunsForRun(ctx, runId), {
+			job: options.job,
+			step: options.step
+		});
+		if (!resolution.ok) {
+			logger.error(pc.red(resolution.error));
+			return false;
+		}
+		logger.info(`Rejecting held run ${pc.cyan(resolution.heldRunId)} for run ${pc.cyan(runId)}...`);
+		if (!await postReject(ctx, resolution.heldRunId, options.reason)) return false;
+		logger.info(pc.yellow("Rejection recorded. The held element will fail."));
+		return true;
+	} catch (error) {
+		logger.error(pc.red(`Error: ${toErrorMessage(error)}`));
+		return false;
+	}
+}
+//#endregion
+export { rejectCommand };
+
+//# sourceMappingURL=reject.js.map

package/dist/commands/run.js

@@ -12,9 +12,9 @@ import { formatJunitResult } from "../remote/output/junit.js";
 import { StreamingFormatter } from "../remote/output/streaming.js";
 import { formatErrorHighlight, formatMultiFixtureSummary, formatSummary } from "../remote/output/summary.js";
 import { compileFixtures, filterFixtures } from "../fixtures/compiler.js";
+import path from "node:path";
 import pc from "picocolors";
 import { readFile, writeFile } from "node:fs/promises";
-import path from "node:path";
 import { formatBytes, logger, toErrorMessage } from "@kici-dev/core";
 //#region src/commands/run.ts
 /**

package/dist/commands/status.js

@@ -15,7 +15,7 @@ import { formatDuration, logger, toErrorMessage } from "@kici-dev/core";
 * Looks up local history first, then fetches from the orchestrator for
 * up-to-date status and logs.
 */
-const CLI_VERSION = "0.1.15";
+const CLI_VERSION = "0.1.16";
 /**
 * Show status and details of a test run.
 *

package/dist/commands/test.js

@@ -6,9 +6,9 @@ import { displayDryRun } from "../test-runner/dry-run.js";
 import { parseEventArg } from "../test-runner/event-types.js";
 import { buildEventPayload } from "../test-runner/payload-builder.js";
 import { loadSecretsFile } from "../test-runner/secrets-file.js";
+import path from "node:path";
 import pc from "picocolors";
 import { readFile } from "node:fs/promises";
-import path from "node:path";
 import { logger, toErrorMessage } from "@kici-dev/core";
 import { matchAllWorkflows, normalizeRunsOn } from "@kici-dev/engine";
 //#region src/commands/test.ts

package/dist/commands/types.js

@@ -1,9 +1,9 @@
 import "../chunk-gOLHoazu.js";
 import { loadGlobalConfig } from "../remote/config.js";
 import { generateSecretsDts } from "../generators/secrets-dts.js";
+import path from "node:path";
 import pc from "picocolors";
 import fs from "node:fs/promises";
-import path from "node:path";
 import { toErrorMessage } from "@kici-dev/core";
 //#region src/commands/types.ts
 /**

package/dist/commands/watch.js

@@ -2,8 +2,8 @@ import "../chunk-gOLHoazu.js";
 import { resolveKiciDir } from "../execution/executor.js";
 import "../execution/index.js";
 import { compileCommand } from "./compile.js";
-import pc from "picocolors";
 import path from "node:path";
+import pc from "picocolors";
 import { logger, toErrorMessage } from "@kici-dev/core";
 import chokidar from "chokidar";
 //#region src/commands/watch.ts

package/dist/execution/executor.js

@@ -2,10 +2,10 @@ import "../chunk-gOLHoazu.js";
 import { compilerError } from "../errors/formatter.js";
 import "../errors/index.js";
 import { ensureTsLoaderHook } from "./ts-loader.js";
+import { pathToFileURL } from "node:url";
+import path from "node:path";
 import { existsSync } from "node:fs";
 import fs from "node:fs/promises";
-import path from "node:path";
-import { pathToFileURL } from "node:url";
 //#region src/execution/executor.ts
 /**
 * Load a TypeScript workflow/config module by direct dynamic import.

package/dist/execution/sdk-alias.js

@@ -1,7 +1,7 @@
 import "../chunk-gOLHoazu.js";
+import path from "node:path";
 import { existsSync } from "node:fs";
 import { readFile } from "node:fs/promises";
-import path from "node:path";
 import { logger } from "@kici-dev/core";
 //#region src/execution/sdk-alias.ts
 /**

package/dist/fixtures/compiler.js

@@ -1,8 +1,8 @@
 import "../chunk-gOLHoazu.js";
 import { ensureTsLoaderHook } from "../execution/ts-loader.js";
-import fs from "node:fs/promises";
-import path from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
+import path from "node:path";
+import fs from "node:fs/promises";
 import picomatch from "picomatch";
 //#region src/fixtures/compiler.ts
 /**

package/dist/fixtures/defaults/index.js

@@ -1,7 +1,7 @@
 import "../../chunk-gOLHoazu.js";
-import { readFileSync } from "node:fs";
-import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+import { readFileSync } from "node:fs";
 //#region src/fixtures/defaults/index.ts
 /**
 * Built-in fixture registry for common GitHub webhook events.

package/dist/hooks/detector.js

@@ -1,6 +1,6 @@
 import "../chunk-gOLHoazu.js";
-import { readFile, stat } from "node:fs/promises";
 import path from "node:path";
+import { readFile, stat } from "node:fs/promises";
 //#region src/hooks/detector.ts
 const TOOL_CONFIGS = [
 	{

package/dist/hooks/installer.js

@@ -1,8 +1,8 @@
 import "../chunk-gOLHoazu.js";
 import { findGitDir } from "./detector.js";
 import { getHookTemplate, hasKiciHook } from "./templates.js";
-import { chmod, mkdir, readFile, stat, writeFile } from "node:fs/promises";
 import path from "node:path";
+import { chmod, mkdir, readFile, stat, writeFile } from "node:fs/promises";
 import { exec } from "node:child_process";
 import { promisify } from "node:util";
 //#region src/hooks/installer.ts

package/dist/index.d.ts

@@ -4,7 +4,7 @@ export { validateConfig } from './validation/index.js';
 export type { ValidationResult } from './validation/index.js';
 export { generateLockFile, serializeLockFile } from './lockfile/index.js';
 export { SCHEMA_VERSION, isLockStaticJob } from './types.js';
-export type { LockFile, LockWorkflow, LockJob, LockDynamicJobFn, LockJobOrFactory, LockTrigger, LockPrTrigger, LockPushTrigger, LockMatrix, LockRule, LockStep, LockSource, LockBranchPattern, } from './types.js';
+export type { LockFile, LockWorkflow, LockJob, LockDynamicJobFn, LockJobOrFactory, LockTrigger, LockPrTrigger, LockPushTrigger, LockMatrix, LockRule, LockStep, LockApproval, LockSource, LockBranchPattern, } from './types.js';
 export { formatError, compilerError, isCompilerError } from './errors/index.js';
 export type { SourceLocation, CompilerError } from './errors/index.js';
 export { CapabilityGapError, formatCapabilityGapError } from './errors/index.js';

package/dist/llm-context/llms-full.txt

@@ -86,7 +86,7 @@ Cross-repo workflows that let a single workflow repo define jobs which run on ev
 
 ---
 
-## Getting started with KiCI
+## Getting started with workflows
 
 Source: https://docs.kici.dev/user/getting-started/
 
@@ -5377,6 +5377,72 @@ kici cancel abc123 --force
 kici cancel --branch feature/wip
 ```
 
+### kici approve
+
+Approve a held [approval gate](approvals.md) so the run resumes. Identify the held element by run ID, optionally narrowed to a job and step.
+
+```bash
+kici approve <run-id> [options]
+```
+
+**Arguments:**
+
+| Argument | Required | Description                        |
+| -------- | -------- | ---------------------------------- |
+| `run-id` | yes      | Run ID holding the gate to approve |
+
+**Options:**
+
+| Option            | Default | Description                                         |
+| ----------------- | ------- | --------------------------------------------------- |
+| `--job <name>`    | none    | Approve a held job (omit for a workflow-level hold) |
+| `--step <name>`   | none    | Approve a held step (used with `--job`)             |
+| `--reason <text>` | none    | Optional note recorded with the approval            |
+
+**Examples:**
+
+```bash
+# Approve a workflow-level hold
+kici approve abc123
+
+# Approve a held job
+kici approve abc123 --job deploy-production
+
+# Approve a held step
+kici approve abc123 --job migrate-and-deploy --step apply-migration
+```
+
+You must be eligible for at least one unsatisfied clause (a member of a named team, or a named user) and hold the `environments:write` or `ci_trust:write` permission. The command reports whether the element was released, how many clauses remain, or that it was rejected.
+
+### kici reject
+
+Reject a held [approval gate](approvals.md). A rejection fails the held element and the run. A reason is required.
+
+```bash
+kici reject <run-id> --reason <text> [options]
+```
+
+**Arguments:**
+
+| Argument | Required | Description                       |
+| -------- | -------- | --------------------------------- |
+| `run-id` | yes      | Run ID holding the gate to reject |
+
+**Options:**
+
+| Option            | Default | Description                                        |
+| ----------------- | ------- | -------------------------------------------------- |
+| `--reason <text>` | none    | Required. Reason recorded with the rejection       |
+| `--job <name>`    | none    | Reject a held job (omit for a workflow-level hold) |
+| `--step <name>`   | none    | Reject a held step (used with `--job`)             |
+
+**Examples:**
+
+```bash
+# Reject a held job with a reason
+kici reject abc123 --job deploy-production --reason "Wrong release branch"
+```
+
 ### kici secrets list
 
 List secret contexts available for test runs. Shows context names and key names (not values).
@@ -6605,6 +6671,58 @@ Practical patterns for building real-world KiCI workflows in TypeScript. The pat
 
 # Workflow features
 
+## Account and sign-in
+
+Source: https://docs.kici.dev/user/account-and-login/
+
+Your KiCI account is a single identity. It stays the same no matter how you
+sign in — whether you signed up with GitHub or with an email and password.
+Changing your sign-in method does not create a new account or move your data;
+your organizations, roles, and API keys stay attached to the same identity.
+
+## Where sign-in methods are managed
+
+Sign-in methods and passwords are managed in your **account console**, provided
+by the identity provider that handles single sign-on for KiCI. The dashboard's
+**Linked accounts** page does not control how you sign in — see
+[Linked accounts vs sign-in methods](#linked-accounts-vs-sign-in-methods) below.
+
+You can open the account console from the dashboard: go to your personal
+settings, open **Linked accounts**, and use the **Account console** link.
+
+## Adding a password to a GitHub-created account
+
+If you registered by signing in with GitHub and now want to sign in with an
+email and password as well:
+
+1. Open your account console.
+2. Add a password (and, if prompted, confirm your email).
+
+After this, you can sign in either with GitHub or with your email and password —
+it is the same account.
+
+## Removing GitHub as a sign-in method
+
+To stop using GitHub to sign in:
+
+1. First add a password (see above). The identity provider will not let you
+   remove your only sign-in method, so you must have another one first.
+2. In your account console, remove the GitHub sign-in method.
+
+Your account, organizations, and data are unaffected — you simply sign in a
+different way afterward.
+
+## Linked accounts vs sign-in methods
+
+The dashboard's **Linked accounts** page controls **run-attribution metadata**
+only — for example, showing your GitHub username on the runs you trigger and
+determining your contributor trust level. Unlinking a provider there removes
+that display link; it does **not** remove the provider as a way to sign in.
+
+To actually change how you sign in, use your account console as described above.
+
+---
+
 ## Concurrency groups
 
 Source: https://docs.kici.dev/user/concurrency/
@@ -7266,6 +7384,16 @@ Create custom roles to restrict what team members can do, or use the built-in **
 
 <!-- /help:settings-roles -->
 
+<!-- help:settings-teams#settings -->
+
+Teams are named groups of organization members. A role granted to a team is inherited by every member, so you can manage permissions for a whole group in one place.
+
+Team names can also be referenced in workflow approval gates (`requireApproval: [{ team: 'leads' }]`) — any member of the named team can satisfy that gate.
+
+Managing teams (create / rename / delete, membership, role grants) requires the **Teams** permission at `admin`; `read` shows a view-only list.
+
+<!-- /help:settings-teams -->
+
 <!-- help:settings-api-keys#settings -->
 
 API keys allow programmatic access to the KiCI API for automation, scripts, and CI integrations.
@@ -7679,7 +7807,9 @@ Use a token's clone button to open the creation modal prefilled with that token'
 
 <!-- help:personal-linked-accounts#account -->
 
-Linked accounts connect your external provider identities (like GitHub) to your KiCI account. Linking enables features like showing your provider username in run metadata and associating your commits with your KiCI identity.
+Linked accounts connect your external provider identities (like GitHub) to your KiCI account. Linking shows your provider username in run metadata and sets your contributor trust level.
+
+**Unlinking here removes the display link only** — it does not remove a sign-in method. To change how you sign in (add a password, remove GitHub login), use the **Account console** link, or see [Account and sign-in](./account-and-login.md).
 
 <!-- /help:personal-linked-accounts -->
 
@@ -7787,6 +7917,8 @@ The standalone account page (`/account`) provides access to personal settings ou
 - **Personal access tokens** -- create and revoke PATs for programmatic API access
 - **Linked accounts** -- connect external provider identities (e.g. GitHub) to your KiCI account
 
+Linked accounts control run-attribution metadata only — unlinking a provider here does not remove it as a way to sign in. To change how you sign in, see [Account and sign-in](./account-and-login.md).
+
 This page is also accessible within an org context via the user menu in the sidebar (`/orgs/:customerId/account`).
 
 ## Admin section
@@ -8227,7 +8359,9 @@ Require manual approval before a job can proceed:
 Required reviewers: alice, bob
 ```
 
-When reviewers are required, the job enters a "held" state. Reviewers can approve or reject via the dashboard or API. Held runs expire after a configurable timeout (default: 1 hour).
+When reviewers are required, the job enters a "held" state. Reviewers can approve or reject via the dashboard, the [`kici approve`](cli-reference.md#kici-approve) command, or the API. Held runs expire after a configurable timeout.
+
+This operator-set rule is the **mandatory** form of an approval gate. Workflow authors can also declare gates in code with `requireApproval` at step, job, or workflow level — see [Approval gates](approvals.md). Both forms use the same held-element mechanism and the same queue.
 
 ### Wait timer