@okfit/cli 0.6.12 → 0.8.0

package/README.md

@@ -1,6 +1,6 @@
 # @okfit/cli
 
-The `okfit` command line for [Open Knowledge Format (OKF)](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md) v0.2 bundles: `okfit validate`, `okfit init`, `okfit context`, `okfit verify`, and `okfit sync`. The full subcommand list is `okf/interfaces/cli-commands.md`'s to keep, not this sentence's to count.
+The `okfit` command line for [Open Knowledge Format (OKF)](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md) v0.2 bundles: `okfit validate`, `okfit init`, `okfit context`, `okfit verify`, `okfit query`, and `okfit sync`. The full subcommand list is `okf/interfaces/cli-commands.md`'s to keep, not this sentence's to count.
 
 > **Part of the okfit kit.** Most users want **[@okfit/plugin](https://www.npmjs.com/package/@okfit/plugin)**, which pulls this package in automatically.
 
@@ -9,9 +9,12 @@ The `okfit` command line for [Open Knowledge Format (OKF)](https://github.com/Go
 ```text
 okfit [--help] [--version]
 okfit validate [path] [--config <file>] [--format human|json] [--skip-provenance] [--document <bundle-path>] [--help]
-okfit init [path] [--profile <name>] [--config <file>] [--help]
+okfit init [path] [--profile <name>] [--bundle <dir>] [--config-location <name>] [--config <file>] [--help]
 okfit context [path] [--config <file>] [--format human|json] [--help]
-okfit verify <id> [path] [--config <file>] [--at <iso>] [--dry-run] [--format human|json] [--help]
+okfit verify [<id>] [path] [--all] [--type <Type>]... [--stable|--draft] [--config <file>] [--at <iso>] [--dry-run] [--format human|json] [--help]
+okfit query list [path] [--type <Type>]... [--tag <tag>]... [--status draft|stable|deprecated]... [--verified|--unverified] [--config <file>] [--format human|json]
+okfit query get <id> [path] [--config <file>] [--format human|json]
+okfit query neighbors <id> [path] [--config <file>] [--format human|json]
 ```
 
 `okfit --version` prints `okfit <cli> (engine <engine>, okf <okf>,
@@ -161,6 +164,21 @@ config's `bundle.profile`, itself defaulting to `software-project`); an
 unrecognised name is a warning, not a failure — `init` continues with the
 default profile.
 
+`--bundle <dir>` sets the bundle directory, relative to the project root
+(default: the config's `bundle.path`, itself defaulting to `okf`). It is
+written to the config's `bundle.path` and is where the scaffold goes. An
+empty, absolute, or root-escaping value (`..`) is a usage error (exit `64`).
+
+`--config-location <.config/okfit.toml|okfit.toml|.okfit.toml>` sets where
+the config file is written (default `.config/okfit.toml`); all three are
+locations discovery already reads.
+
+When the run is interactive, `init` asks for each of the profile, the bundle
+directory, and the config location that was not given as a flag, in that
+order, with the default pre-selected. Esc or Ctrl-C at any prompt exits `130`
+with `cancelled; nothing written`; every prompt happens before the first
+write. Piped or scripted runs never prompt and behave exactly as before.
+
 ### `okfit context`
 
 Prints the resolved project root, bundle root, config path, profile, and
@@ -220,9 +238,52 @@ file and an atomic rename, and the target's mode is preserved on the
 replacement, but the file is not skipped just because it is `chmod`-ed
 read-only.
 
+`--stable` or `--draft` sets the concept's `status` in the same write as the
+attestation, so settling a reviewed draft is one command:
+`okfit verify <id> --stable`. Passing both is a usage error (exit `64`), as
+is passing either with `--all` or `--type`: promotion is a per-concept
+decision. A concept already at the requested status gets no status edit. The
+human line ends `; status <from> -> <to>`, `; status already <to>` or
+`; status (absent) -> <to>`, and a dry run adds a `would set status:` line
+with the exact fragment.
+
+`--all` and `--type <Type>` (repeatable) attest in batch: every concept whose
+type sets `require_verified` (or of the named types) that you have not
+already verified. A batch skips a concept and reports why: `draft`,
+`deprecated`, or `already-verified`. A batch never re-attests a
+`deprecated` concept; verifying one by id is still allowed.
+
+Bare `okfit verify` in a terminal opens a picker: every concept of a
+`require_verified` type you have not attested, drafts included and
+deprecated excluded, grouped by type (↑/↓ move, space toggles, `a` toggles a
+section, Enter continues). A confirm step follows, with a "promote K drafts
+to stable" toggle that is on by default. The picked concepts are attested in
+one all-or-nothing write. Esc, `q`, Ctrl-C or answering no exits `130` with
+nothing written. Without a terminal (a pipe, an agent or CI audience, or
+`--format json`) bare `verify` is a usage error (exit `64`).
+
 This is a human-run command: it records **your** attestation that you
 reviewed the concept, so no agent, hook, or MCP tool ever invokes it.
 
+### `okfit query`
+
+Read-only lookups over the bundle, backed by the engine's `ConceptQuery`
+layer (the same one the MCP `list_concepts`, `get_concept` and
+`concept_neighbors` tools use). Bare `okfit query` prints help.
+
+- `okfit query list [path]` lists concepts as summaries (id, type, title,
+  description, status, tags, path). Filters: `--type <Type>` and
+  `--tag <tag>` (repeatable, each must be declared in the config),
+  `--status draft|stable|deprecated` (repeatable), and `--verified` or
+  `--unverified`.
+- `okfit query get <id> [path]` prints one concept: the summary fields and its
+  outgoing links. `--format json` also includes the raw frontmatter.
+- `okfit query neighbors <id> [path]` prints a concept's outgoing and
+  incoming links.
+
+Exit `0` on success, `3` for an unknown id, `64` for an undeclared type or
+tag or for `--verified` together with `--unverified`.
+
 ## Config discovery
 
 With no `--config` flag, `okfit` walks upward from `[path]` (default:
@@ -347,6 +408,19 @@ envelope to stdout and exits `3`:
 
 `init` has no `--format`; it is human output only.
 
+`okfit verify --format json` prints `VerifyEnvelope` (`schema`, `okfit_version`,
+`engine_version`, `distribution`, `id`, `path`, `verified`, `status`,
+`dry_run`, `exit_code`), where `status` is `{ "from": ..., "to": ... }` when
+`--stable` or `--draft` was given and `null` otherwise. With `--all` or
+`--type` it prints `VerifyBatchEnvelope`, whose `skipped[].reason` is one of
+`draft`, `deprecated` or `already-verified`.
+
+`okfit query list --format json` prints `QueryListEnvelope` (`total`, `items`);
+`query get` prints `QueryGetEnvelope` (`concept`: the summary fields plus
+`frontmatter` and `links`); `query neighbors` prints `QueryNeighborsEnvelope`
+(`id`, `outgoing`, `incoming`). Each carries `schema`, `okfit_version`,
+`engine_version` and `distribution`.
+
 `okfit context --format json` prints its own envelope, distinct from the
 one above:
 

package/commands/context.js

@@ -1,4 +1,3 @@
-import { setExitCode } from "../internal/exit.js";
 import { humanContext } from "../render/context.js";
 import { CLI_VERSION } from "../version.js";
 import { Argument, Command, Flag } from "effect/cli";
@@ -64,7 +63,6 @@ const contextCommand = Command.make("context", {
 		});
 		if (input.format === "json") yield* Console.log(JSON.stringify(Schema.encodeSync(ContextEnvelope)(envelope)));
 		else for (const contextLine of humanContext(envelope)) yield* Console.log(contextLine);
-		setExitCode(0);
 	}).pipe(provideConfig({
 		explicitConfigPath: input.config,
 		discoveryCwd

package/commands/graph.js

@@ -1,4 +1,3 @@
-import { setExitCode } from "../internal/exit.js";
 import { CLI_VERSION } from "../version.js";
 import { Argument, Command, Flag } from "effect/cli";
 import { CurrentDistribution } from "@effected/engine";
@@ -65,7 +64,6 @@ const graphCommand = Command.make("graph", {
 			yield* Console.log(JSON.stringify(Schema.encodeSync(GraphEnvelope)(envelope)));
 		} else if (input.format === "dot") yield* Console.log(result.graph.toGraphViz());
 		else yield* Console.log(result.graph.toMermaid());
-		setExitCode(0);
 	}).pipe(provideConfig({
 		explicitConfigPath: input.config,
 		discoveryCwd

package/commands/init.js

@@ -1,10 +1,10 @@
-import { setExitCode } from "../internal/exit.js";
+import { INIT_CONFIG_LOCATIONS, initWizard } from "../internal/initWizard.js";
 import { displayRoot, human, summary } from "../render/human.js";
+import { CliExit, CliTheme } from "@effected/cli";
 import { Argument, Command, Flag } from "effect/cli";
 import { CONFIG_RELATIVE_PATH, InitOverwriteError, Now, collect, configValue, files, forDiagnostics, provideConfig, resolveBundleRoot, resolveProjectRoot, run, targetPaths } from "@okfit/engine";
 import { Console, DateTime, Effect, FileSystem, Layer, Option, Path } from "effect";
 import { OKF_SPEC_VERSION, OkfitConfig, OkfitConfigFile, SCHEMA_DIRECTIVE } from "@okfit/core";
-import { CliColor } from "@effected/cli";
 import { Git } from "@effected/git";
 import { GitHistory, Profiles } from "@okfit/profiles";
 
@@ -23,7 +23,11 @@ const configFlag = Flag.File("config").pipe(Flag.optional, Flag.withDescription(
 * CLI-rendered warning (K-4), matching `Profiles.get`'s own `Option.none`
 * contract (P-38), not a parser-level `CliError.InvalidValue`.
 */
-const profileFlag = Flag.String("profile").pipe(Flag.optional, Flag.withDescription("profile to scaffold with (default: the config's bundle.profile or software-project)"));
+const profileFlag = Flag.String("profile").pipe(Flag.optional, Flag.withDescription("profile to scaffold with (default: the config's bundle.profile or software-project; prompted for when interactive)"));
+/** `--bundle <dir>`: project-relative; validated by the wizard before anything else (usage error, exit 64). */
+const bundleFlag = Flag.String("bundle").pipe(Flag.optional, Flag.withDescription("bundle directory, relative to the project root (default: the config's bundle.path or okf; prompted for when interactive)"));
+/** `--config-location`: where the config file is written, one of the three discovered names (C-1). */
+const configLocationFlag = Flag.Literals("config-location", INIT_CONFIG_LOCATIONS).pipe(Flag.optional, Flag.withDescription("where to write the config file (default: .config/okfit.toml; prompted for when interactive)"));
 /**
 * Stands in for `profile.config` when `Profiles.get` returns `None`.
 * `OkfitConfig.merge` only visits `Object.keys(override)`
@@ -48,8 +52,13 @@ const countsOf = (diagnostics, concepts) => ({
 	concepts
 });
 /**
-* `okfit init [path] [--profile <name>] [--config <file>]` (K-2, K-3; no
-* `--format`, human output only, K-6).
+* `okfit init [path] [--profile <name>] [--bundle <dir>] [--config-location <name>]
+* [--config <file>]` (K-2, K-3; no `--format`, human output only, K-6).
+*
+* Interactive runs prompt (the kit's Ink screens, `initWizard`) for each of
+* profile, bundle directory and config location whose flag was not given;
+* every prompt happens after discovery and before any write (step 4), so a
+* cancel exits 130 with nothing written.
 *
 * Handler order, fixed by the contract:
 *
@@ -61,7 +70,8 @@ const countsOf = (diagnostics, concepts) => ({
 *     `sources[0]`.
 *  4. `profileName = Option.getOrElse(input.profile, () =>
 *     fileConfig.bundle?.profile ?? DEFAULTS.bundle.profile)` (K-3, the one
-*     difference from `validate`'s step 4). `Profiles.get(profileName)`.
+*     difference from `validate`'s step 4), then `--bundle`/`--config-location`
+*     likewise, all three through `initWizard`. `Profiles.get(profileName)`.
 *     `None` and `profileName !== "none"` warns (K-4); `"none"` is silent.
 *  5. `merged = OkfitConfig.merge(OkfitConfig.merge(DEFAULTS, profileConfig),
 *     fileConfig)`, `profileConfig` falling back to `NO_PROFILE_CONFIG` when
@@ -81,19 +91,15 @@ const countsOf = (diagnostics, concepts) => ({
 * 10. `Console.log` the K-51 success line.
 * 11. self-validate (K-29): `run({ root: bundleRoot, config: merged,
 *     profile, now })` over the bundle just written, rendered exactly as
-*     `validate --format human` does, `setExitCode` to its
+*     `validate --format human` does, `CliExit.set` to its
 *     `forDiagnostics` result. The handler SUCCEEDS (K-7); the failure path
 *     is only `InitOverwriteError` at step 8, or an infrastructure error
 *     that already carries its own `[Runtime.errorExitCode]`.
 *
 * @public
 */
-const initCommand = Command.make("init", {
-	path: pathArg,
-	config: configFlag,
-	profile: profileFlag
-}, (input) => Effect.gen(function* () {
-	const cwd = process.cwd();
+/** The `init` handler body, parameterised on `cwd` so tests can drive it against a temp project. */
+const initProgram = (input, cwd) => Effect.gen(function* () {
 	const discoveryCwd = Option.getOrElse(input.path, () => cwd);
 	yield* provideConfig({
 		explicitConfigPath: input.config,
@@ -102,14 +108,31 @@ const initCommand = Command.make("init", {
 		const configFile = yield* OkfitConfigFile;
 		const winner = (yield* configFile.discover)[0];
 		const fileConfig = winner === void 0 ? { extensions: {} } : winner.value;
-		const profileName = Option.getOrElse(input.profile, () => fileConfig.bundle?.profile ?? DEFAULT_PROFILE_NAME);
+		const defaultBundle = fileConfig.bundle?.path ?? DEFAULT_BUNDLE_PATH;
+		const answers = yield* initWizard({
+			profile: input.profile,
+			bundle: input.bundle,
+			location: input.configLocation
+		}, {
+			profile: fileConfig.bundle?.profile ?? DEFAULT_PROFILE_NAME,
+			bundle: defaultBundle,
+			location: CONFIG_RELATIVE_PATH
+		});
+		const profileName = answers.profile;
 		const profile = Profiles.get(profileName);
 		if (Option.isNone(profile) && profileName !== "none") yield* Console.error(`warning: unknown profile "${profileName}"; continuing with defaults`);
 		const profileConfig = Option.match(profile, {
 			onNone: () => NO_PROFILE_CONFIG,
 			onSome: (resolved) => resolved.config
 		});
-		const merged = OkfitConfig.merge(OkfitConfig.merge(OkfitConfig.DEFAULTS, profileConfig), fileConfig);
+		const mergedBase = OkfitConfig.merge(OkfitConfig.merge(OkfitConfig.DEFAULTS, profileConfig), fileConfig);
+		const merged = {
+			...mergedBase,
+			bundle: {
+				...mergedBase.bundle,
+				path: answers.bundle
+			}
+		};
 		if (merged.okf_version !== void 0 && merged.okf_version !== OKF_SPEC_VERSION) yield* Console.error(`warning: okf_version "${merged.okf_version}" does not match this okfit's spec version "${OKF_SPEC_VERSION}"; continuing`);
 		const path = yield* Path.Path;
 		const fs = yield* FileSystem.FileSystem;
@@ -143,12 +166,14 @@ const initCommand = Command.make("init", {
 			paths: existing,
 			cwd
 		});
-		for (const target of paths) yield* fs.makeDirectory(path.dirname(target), { recursive: true });
-		const bundlePath = merged.bundle?.path ?? DEFAULT_BUNDLE_PATH;
+		const configTargets = new Set(INIT_CONFIG_LOCATIONS.map((location) => `${projectRoot}/${location}`));
+		const written = [...paths.filter((target) => !configTargets.has(target)), `${projectRoot}/${answers.location}`];
+		for (const target of written) yield* fs.makeDirectory(path.dirname(target), { recursive: true });
+		const bundlePath = answers.bundle;
 		yield* configFile.write(configValue({
 			...scaffoldOptions,
 			bundlePath
-		}), `${projectRoot}/${CONFIG_RELATIVE_PATH}`, { header: SCHEMA_DIRECTIVE });
+		}), `${projectRoot}/${answers.location}`, { header: SCHEMA_DIRECTIVE });
 		const scaffoldFiles = yield* files(scaffoldOptions);
 		for (const file of scaffoldFiles) yield* fs.writeFileString(file.path, file.contents);
 		yield* Console.log(`Initialized ${displayRoot(cwd, bundleRoot, path)} with the ${profileName} profile`);
@@ -159,12 +184,20 @@ const initCommand = Command.make("init", {
 			now
 		}).pipe(Effect.provide(Layer.mergeAll(Git.layer, GitHistory.layer)));
 		const diagnostics = collect(result.report.conformance, result.report.lint, result.profileDiagnostics);
-		const color = yield* CliColor.enabled;
-		for (const line of human(diagnostics, { color })) yield* Console.log(line);
+		const theme = yield* CliTheme;
+		for (const line of human(diagnostics, { paint: theme.paint })) yield* Console.log(line);
 		yield* Console.error(summary(countsOf(diagnostics, result.bundle.concepts.size), displayRoot(cwd, bundleRoot, path)));
-		setExitCode(forDiagnostics(diagnostics));
+		yield* CliExit.set(forDiagnostics(diagnostics));
 	}));
-})).pipe(Command.withDescription("Scaffold a new OKF bundle: a config file, the bundle's root and per-directory index files, a project stub, and an initial log entry."));
+});
+/** @public */
+const initCommand = Command.make("init", {
+	path: pathArg,
+	config: configFlag,
+	profile: profileFlag,
+	bundle: bundleFlag,
+	configLocation: configLocationFlag
+}, (input) => initProgram(input, process.cwd())).pipe(Command.withDescription("Scaffold a new OKF bundle: a config file, the bundle's root and per-directory index files, a project stub, and an initial log entry."));
 
 //#endregion
-export { initCommand };
+export { initCommand, initProgram };

package/commands/lint.js

@@ -1,12 +1,11 @@
-import { setExitCode } from "../internal/exit.js";
 import { CLI_VERSION } from "../version.js";
 import { displayRoot, human, summary } from "../render/human.js";
+import { CliExit, CliTheme } from "@effected/cli";
 import { Argument, Command, Flag } from "effect/cli";
 import { CurrentDistribution } from "@effected/engine";
 import { JsonEnvelope, Now, collect, forDiagnostics, json, jsonError, provideConfig, resolveProjectConfig, run } from "@okfit/engine";
 import { Console, Effect, Layer, Option, Path, Schema } from "effect";
 import { OKF_SPEC_VERSION } from "@okfit/core";
-import { CliColor } from "@effected/cli";
 import { Git } from "@effected/git";
 import { GitHistory } from "@okfit/profiles";
 
@@ -76,8 +75,8 @@ const lintCommand = Command.make("lint", {
 			});
 			yield* Console.log(JSON.stringify(Schema.encodeSync(JsonEnvelope)(envelope)));
 		} else {
-			const color = yield* CliColor.enabled;
-			for (const diagnosticLine of human(diagnostics, { color })) yield* Console.log(diagnosticLine);
+			const theme = yield* CliTheme;
+			for (const diagnosticLine of human(diagnostics, { paint: theme.paint })) yield* Console.log(diagnosticLine);
 			const counts = {
 				errors: diagnostics.filter((d) => d.severity === "error").length,
 				warnings: diagnostics.filter((d) => d.severity === "warning").length,
@@ -86,7 +85,7 @@ const lintCommand = Command.make("lint", {
 			};
 			yield* Console.error(summary(counts, displayRoot(cwd, bundleRoot, path)));
 		}
-		setExitCode(code);
+		yield* CliExit.set(code);
 	}).pipe(provideConfig({
 		explicitConfigPath: input.config,
 		discoveryCwd

package/commands/query.js

@@ -0,0 +1,172 @@
+import { CLI_VERSION } from "../version.js";
+import { displayRoot } from "../render/human.js";
+import { humanQueryGet, humanQueryList, humanQueryNeighbors, queryListSummary } from "../render/query.js";
+import { Argument, Command, Flag } from "effect/cli";
+import { CurrentDistribution } from "@effected/engine";
+import { ConceptQuery, QueryGetEnvelope, QueryListEnvelope, QueryNeighborsEnvelope, QuerySelectionError, jsonError, provideConfig, queryGetEnvelope, queryListEnvelope, queryNeighborsEnvelope, resolveProjectConfig, toConceptSummary } from "@okfit/engine";
+import { Console, Effect, Option, Path, Schema } from "effect";
+import { Bundle } from "@okfit/core";
+
+//#region src/commands/query.ts
+/** `[path]` is the PROJECT root (K-2), never the bundle root. Absolute at parse time (K-50). */
+const pathArg = Argument.Path("path", { pathType: "directory" }).pipe(Argument.optional, Argument.withDescription("project root to start config discovery from (default: current directory); never the bundle root"));
+const idArg = Argument.String("id").pipe(Argument.withDescription("concept id, with or without a leading slash or trailing .md"));
+/** K-1: no `mustExist` — the handler stats the path itself, before building any layer. */
+const configFlag = Flag.File("config").pipe(Flag.optional, Flag.withDescription("explicit config file; skips discovery"));
+const formatFlag = Flag.Literals("format", ["human", "json"]).pipe(Flag.withDefault("human"), Flag.withDescription("output format: human (default) or json"));
+const typeFlag = Flag.String("type").pipe(Flag.atLeast(0), Flag.withDescription("only concepts of this type (repeatable; any match)"));
+const tagFlag = Flag.String("tag").pipe(Flag.atLeast(0), Flag.withDescription("only concepts carrying this tag (repeatable; all must match)"));
+const statusFlag = Flag.Literals("status", [
+	"draft",
+	"stable",
+	"deprecated"
+]).pipe(Flag.atLeast(0), Flag.withDescription("only concepts with this status (repeatable; any match)"));
+const verifiedFlag = Flag.Boolean("verified").pipe(Flag.withDefault(false), Flag.withDescription("only concepts with at least one verified entry"));
+const unverifiedFlag = Flag.Boolean("unverified").pipe(Flag.withDefault(false), Flag.withDescription("only concepts with no verified entry"));
+/**
+* Shared skeleton: discover config, load the bundle, run `use`, and — under
+* `--format json` — apply the K-22 stdout error envelope. `precheck` runs
+* first, before any config discovery, so an invalid flag combination fails fast.
+*/
+const run$1 = (input, use, precheck) => Effect.gen(function* () {
+	const cwd = process.cwd();
+	const discoveryCwd = Option.getOrElse(input.path, () => cwd);
+	const path = yield* Path.Path;
+	const distribution = yield* CurrentDistribution;
+	const body = Effect.gen(function* () {
+		if (precheck !== void 0) yield* precheck;
+		const resolved = yield* resolveProjectConfig({
+			pathArg: input.path,
+			explicitConfigPath: input.config,
+			cwd
+		});
+		yield* use({
+			bundle: yield* Bundle.load({ root: resolved.bundleRoot }),
+			config: resolved.config,
+			root: displayRoot(cwd, resolved.bundleRoot, path),
+			distribution
+		});
+	}).pipe(provideConfig({
+		explicitConfigPath: input.config,
+		discoveryCwd
+	}));
+	if (input.format === "json") return yield* body.pipe(Effect.tapError((error) => Console.log(JSON.stringify(jsonError(error, CLI_VERSION, Option.getOrUndefined(distribution))))));
+	return yield* body;
+});
+const distributionOf = (distribution) => Option.isSome(distribution) ? { distribution: distribution.value } : {};
+/**
+* `okfit query list [path] [--type <T>]... [--tag <t>]... [--status <s>]...
+* [--verified|--unverified] [--config <file>] [--format human|json]`.
+*
+* @public
+*/
+const queryListCommand = Command.make("list", {
+	path: pathArg,
+	config: configFlag,
+	type: typeFlag,
+	tag: tagFlag,
+	status: statusFlag,
+	verified: verifiedFlag,
+	unverified: unverifiedFlag,
+	format: formatFlag
+}, (input) => {
+	const filter = {
+		...input.type.length > 0 ? { types: input.type } : {},
+		...input.tag.length > 0 ? { tags: input.tag } : {},
+		...input.status.length > 0 ? { statuses: input.status } : {},
+		...input.verified ? { verified: true } : {},
+		...input.unverified ? { verified: false } : {}
+	};
+	return run$1(input, ({ bundle, config, root, distribution }) => Effect.gen(function* () {
+		const items = (yield* ConceptQuery.list(bundle, config, filter)).map(toConceptSummary);
+		if (input.format === "json") {
+			const envelope = queryListEnvelope({
+				okfitVersion: CLI_VERSION,
+				total: items.length,
+				items,
+				...distributionOf(distribution)
+			});
+			yield* Console.log(JSON.stringify(Schema.encodeSync(QueryListEnvelope)(envelope)));
+		} else {
+			for (const line of humanQueryList(items)) yield* Console.log(line);
+			yield* Console.error(queryListSummary(items.length, root));
+		}
+	}), input.verified && input.unverified ? Effect.fail(new QuerySelectionError({ reason: "verified-conflict" })) : void 0);
+}).pipe(Command.withDescription("List concepts, sorted by id, optionally filtered by type, tag, status, or verified state."));
+/**
+* `okfit query get <id> [path] [--config <file>] [--format human|json]`.
+*
+* @public
+*/
+const queryGetCommand = Command.make("get", {
+	id: idArg,
+	path: pathArg,
+	config: configFlag,
+	format: formatFlag
+}, (input) => run$1(input, ({ bundle, distribution }) => Effect.gen(function* () {
+	const { concept, links } = yield* ConceptQuery.get(bundle, input.id);
+	const summary = toConceptSummary(concept);
+	if (input.format === "json") {
+		const envelope = queryGetEnvelope({
+			okfitVersion: CLI_VERSION,
+			concept: summary,
+			frontmatter: concept.frontmatter.raw,
+			links,
+			...distributionOf(distribution)
+		});
+		yield* Console.log(JSON.stringify(Schema.encodeSync(QueryGetEnvelope)(envelope)));
+	} else for (const line of humanQueryGet({
+		summary,
+		verified: concept.frontmatter.verified ?? [],
+		links
+	})) yield* Console.log(line);
+}))).pipe(Command.withDescription("Show one concept: its fields, verified entries, and outgoing links."));
+/**
+* `okfit query neighbors <id> [path] [--config <file>] [--format human|json]`.
+*
+* @public
+*/
+const queryNeighborsCommand = Command.make("neighbors", {
+	id: idArg,
+	path: pathArg,
+	config: configFlag,
+	format: formatFlag
+}, (input) => run$1(input, ({ bundle, distribution }) => Effect.gen(function* () {
+	const result = yield* ConceptQuery.neighbors(bundle, input.id);
+	const project = (n) => ({
+		id: n.id,
+		kind: n.kind,
+		summary: n.concept === null ? null : toConceptSummary(n.concept)
+	});
+	const outgoing = result.outgoing.map(project);
+	const incoming = result.incoming.map(project);
+	if (input.format === "json") {
+		const envelope = queryNeighborsEnvelope({
+			okfitVersion: CLI_VERSION,
+			id: result.id,
+			outgoing,
+			incoming,
+			...distributionOf(distribution)
+		});
+		yield* Console.log(JSON.stringify(Schema.encodeSync(QueryNeighborsEnvelope)(envelope)));
+	} else for (const line of humanQueryNeighbors({
+		outgoing,
+		incoming
+	})) yield* Console.log(line);
+}))).pipe(Command.withDescription("Show the concepts a concept links to and the ones that link to it."));
+/**
+* `okfit query`: read-only questions about the bundle, one subcommand per
+* MCP query tool (`list_concepts`, `get_concept`, `concept_neighbors`) over
+* the same `@okfit/engine` `ConceptQuery`. No handler: bare `okfit query`
+* prints help and exits 0, the root command's own K-5 behaviour.
+*
+* @public
+*/
+const queryCommand = Command.make("query", {}).pipe(Command.withDescription("Read-only queries over the bundle: list, get, neighbors."), Command.withSubcommands([
+	queryListCommand,
+	queryGetCommand,
+	queryNeighborsCommand
+]));
+
+//#endregion
+export { queryCommand, queryGetCommand, queryListCommand, queryNeighborsCommand };

package/commands/root.js

@@ -2,10 +2,12 @@ import { contextCommand } from "./context.js";
 import { graphCommand } from "./graph.js";
 import { initCommand } from "./init.js";
 import { lintCommand } from "./lint.js";
+import { queryCommand } from "./query.js";
 import { staleCommand } from "./stale.js";
 import { syncCommand } from "./sync.js";
 import { validateCommand } from "./validate.js";
 import { verifyCommand } from "./verify.js";
+import { CliAudience } from "@effected/cli";
 import { Command } from "effect/cli";
 
 //#region src/commands/root.ts
@@ -17,8 +19,9 @@ import { Command } from "effect/cli";
 * `okfit` therefore prints the root help and exits `0` with no code in this
 * package at all.
 *
-* `validate`, `init`, `context`, `verify`, `sync`, `lint`, `graph`, and
-* `stale` are the whole command tree; nothing else is registered here.
+* `validate`, `init`, `context`, `verify`, `sync`, `lint`, `graph`,
+* `stale`, and `query` (with its `list`/`get`/`neighbors`) are the whole
+* command tree; nothing else is registered here.
 * Each is appended in introduction order, never reordered in, so
 * `--help`'s subcommand list reads that way too (contract §4.2). The
 * top-level description is left unchanged: neither `context` nor `verify`
@@ -27,7 +30,7 @@ import { Command } from "effect/cli";
 *
 * @public
 */
-const rootCommand = Command.make("okfit", {}).pipe(Command.withDescription("Open Knowledge Format (OKF) v0.2 tooling: validate and scaffold bundles."), Command.withSubcommands([
+const rootCommand = Command.make("okfit", {}).pipe(Command.withDescription("Open Knowledge Format (OKF) v0.2 tooling: validate and scaffold bundles."), Command.withSharedFlags(CliAudience.flags()), Command.withSubcommands([
 	validateCommand,
 	initCommand,
 	contextCommand,
@@ -35,7 +38,8 @@ const rootCommand = Command.make("okfit", {}).pipe(Command.withDescription("Open
 	syncCommand,
 	lintCommand,
 	graphCommand,
-	staleCommand
+	staleCommand,
+	queryCommand
 ]));
 
 //#endregion

package/commands/stale.js

@@ -1,4 +1,3 @@
-import { setExitCode } from "../internal/exit.js";
 import { CLI_VERSION } from "../version.js";
 import { displayRoot } from "../render/human.js";
 import { humanStale, staleSummary } from "../render/stale.js";
@@ -66,7 +65,6 @@ const staleCommand = Command.make("stale", {
 			for (const line of humanStale(envelope.items)) yield* Console.log(line);
 			yield* Console.error(staleSummary(envelope.summary.stale, envelope.summary.concepts, displayRoot(cwd, bundleRoot, path)));
 		}
-		setExitCode(0);
 	}).pipe(provideConfig({
 		explicitConfigPath: input.config,
 		discoveryCwd

package/commands/sync.js

@@ -1,4 +1,3 @@
-import { setExitCode } from "../internal/exit.js";
 import { CLI_VERSION } from "../version.js";
 import { displayRoot } from "../render/human.js";
 import { humanSync } from "../render/sync.js";
@@ -110,7 +109,6 @@ const syncCommand = Command.make("sync", {
 			});
 			yield* Console.log(JSON.stringify(Schema.encodeSync(SyncEnvelope)(envelope)));
 		} else for (const line of humanSync(result)) yield* Console.log(line);
-		setExitCode(0);
 	}).pipe(provideConfig({
 		explicitConfigPath: input.config,
 		discoveryCwd

package/commands/validate.js

@@ -1,13 +1,12 @@
-import { setExitCode } from "../internal/exit.js";
 import { CLI_VERSION } from "../version.js";
 import { displayRoot, human, summary } from "../render/human.js";
 import { readDocumentText } from "../internal/stdin.js";
+import { CliExit, CliTheme } from "@effected/cli";
 import { Argument, Command, Flag } from "effect/cli";
 import { CurrentDistribution } from "@effected/engine";
 import { JsonEnvelope, Now, collect, forDiagnostics, json, jsonError, provideConfig, provideDocuments, resolveProjectConfig, run } from "@okfit/engine";
 import { Console, Effect, Layer, Option, Path, Schema } from "effect";
 import { OKF_SPEC_VERSION } from "@okfit/core";
-import { CliColor } from "@effected/cli";
 import { Git } from "@effected/git";
 import { GitHistory } from "@okfit/profiles";
 
@@ -83,8 +82,8 @@ const validateCommand = Command.make("validate", {
 			});
 			yield* Console.log(JSON.stringify(Schema.encodeSync(JsonEnvelope)(envelope)));
 		} else {
-			const color = yield* CliColor.enabled;
-			for (const diagnosticLine of human(diagnostics, { color })) yield* Console.log(diagnosticLine);
+			const theme = yield* CliTheme;
+			for (const diagnosticLine of human(diagnostics, { paint: theme.paint })) yield* Console.log(diagnosticLine);
 			const counts = {
 				errors: diagnostics.filter((d) => d.severity === "error").length,
 				warnings: diagnostics.filter((d) => d.severity === "warning").length,
@@ -93,7 +92,7 @@ const validateCommand = Command.make("validate", {
 			};
 			yield* Console.error(summary(counts, displayRoot(cwd, bundleRoot, path)));
 		}
-		setExitCode(code);
+		yield* CliExit.set(code);
 	}).pipe(provideConfig({
 		explicitConfigPath: input.config,
 		discoveryCwd