@okfit/cli 0.1.0 → 0.2.0

package/commands/root.js

@@ -1,13 +1,36 @@
-import { Console } from "effect";
+import { contextCommand } from "./context.js";
+import { initCommand } from "./init.js";
+import { syncCommand } from "./sync.js";
+import { validateCommand } from "./validate.js";
+import { verifyCommand } from "./verify.js";
 import { Command } from "effect/unstable/cli";
 
 //#region src/commands/root.ts
 /**
-* The `okfit` root command. Subcommands are attached in later releases.
+* K-5. No handler: the framework's own default for a command with neither a
+* `handle` nor a matched subcommand is
+* `Effect.fail(new CliError.ShowHelp({ commandPath, errors: [] }))`, and a
+* `ShowHelp` with no errors carries `[Runtime.errorExitCode] = 0`. Bare
+* `okfit` therefore prints the root help and exits `0` with no code in this
+* package at all.
+*
+* `validate`, `init`, `context`, `verify`, and `sync` 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` validates or scaffolds, but widening the sentence
+* for the orientation- and attestation-only commands buys nothing
+* (contract §4.2).
 *
 * @public
 */
-const rootCommand = Command.make("okfit", {}, () => Console.log("okfit: no subcommands are available yet. Run `okfit --help`."));
+const rootCommand = Command.make("okfit", {}).pipe(Command.withDescription("Open Knowledge Format (OKF) v0.2 tooling: validate and scaffold bundles."), Command.withSubcommands([
+	validateCommand,
+	initCommand,
+	contextCommand,
+	verifyCommand,
+	syncCommand
+]));
 
 //#endregion
 export { rootCommand };

package/commands/sync.js

@@ -0,0 +1,111 @@
+import { provideConfig } from "../config/layer.js";
+import { resolveProjectConfig } from "../config/resolve.js";
+import { setExitCode } from "../internal/exit.js";
+import { jsonError } from "../render/json.js";
+import { CLI_VERSION } from "../version.js";
+import { displayRoot } from "../render/human.js";
+import { runSync } from "../sync/run.js";
+import { SyncEnvelope, humanSync, syncEnvelope } from "../render/sync.js";
+import { Argument, Command, Flag } from "effect/unstable/cli";
+import { Console, Effect, Layer, Option, Path, Schema } from "effect";
+import { GitHistory } from "@okfit/profiles";
+import { Git } from "@effected/git";
+
+//#region src/commands/sync.ts
+/** K-2: `[path]` is the PROJECT root, byte-identical to validate/init/context/verify's. */
+const pathArg = Argument.path("path", { pathType: "directory" }).pipe(Argument.optional, Argument.withDescription("project root to start config discovery from (default: current directory)"));
+/** K-1: no `mustExist` — the handler stats it via `provideConfig`. */
+const configFlag = Flag.file("config").pipe(Flag.optional, Flag.withDescription("explicit config file; skips discovery"));
+/**
+* S-13: a REPEATED `Flag.choice`, not a comma-separated `Flag.string`.
+* `Flag.atLeast(0)` allows zero occurrences (all three modes run) up
+* through any number. Each occurrence is independently validated by the
+* underlying `Choice` primitive, so a bad token (`--only badmode`) is a
+* genuine parse-time `CliError.InvalidValue` → `ShowHelp` → `bin.ts`'s
+* existing 64 remap — no new error class, no hand-built `ShowHelp`
+* (contract §11, S-13, judge note 9).
+*
+* Note: `Flag.choice`'s installed signature (`effect/unstable/cli/Flag.d.ts:161`)
+* takes `(name: string, choices: ReadonlyArray<string>)`, matching
+* `formatFlag` below — not the `[value, label]` tuple-pair form
+* `Flag.choiceWithValue` takes. The contract's own `onlyFlag` sketch
+* writes tuple pairs; since every pair's two elements are identical
+* (`["generated", "generated"]`, etc.), the plain string-array form
+* below is the same flag, verified against the installed primitive
+* rather than copied byte-for-byte from the contract's prose.
+*/
+const onlyFlag = Flag.choice("only", [
+	"generated",
+	"index",
+	"log"
+]).pipe(Flag.atLeast(0), Flag.withDescription("restrict the run to these modes (repeatable: --only generated --only index); default: all three"));
+const dryRunFlag = Flag.boolean("dry-run").pipe(Flag.withDefault(false), Flag.withDescription("compute every result and write nothing"));
+const formatFlag = Flag.choice("format", ["human", "json"]).pipe(Flag.withDefault("human"), Flag.withDescription("output format: human (default) or json"));
+/**
+* `okfit sync [path] [--config <file>] [--only <mode>]... [--dry-run]
+* [--format human|json]`.
+*
+* Handler order fixed by contract §4.3. Steps 1–3 are `context`'s/
+* `validate`'s handler in substance — stat `--config` (K-1) via
+* `provideConfig`, resolve the project and bundle roots through
+* `resolveProjectConfig` — then it diverges: build the `--only` mode
+* set (default: all three, order irrelevant — `runSync`'s own fixed
+* order wins, not `--only`'s occurrence order), run `runSync` with BOTH
+* `Git.layer` and `GitHistory.layer` provided (S-16, mirroring
+* `verify.ts:134`'s `Git.layer`-alone provision one layer up: here two
+* layers are needed because `GitHistory.layer` does not re-expose `Git`
+* even though it is built on it), render, and always exit `0`. There is
+* no content tier: every typed failure is exit `3` through `bin.ts`'s
+* existing `reportFailures`; an unknown `--only` token never reaches
+* this handler at all — it fails at parse time, exit `64`.
+*
+* @public
+*/
+const syncCommand = Command.make("sync", {
+	path: pathArg,
+	config: configFlag,
+	only: onlyFlag,
+	dryRun: dryRunFlag,
+	format: formatFlag
+}, (input) => Effect.gen(function* () {
+	const cwd = process.cwd();
+	const discoveryCwd = Option.getOrElse(input.path, () => cwd);
+	const body = Effect.gen(function* () {
+		const path = yield* Path.Path;
+		const resolved = yield* resolveProjectConfig({
+			pathArg: input.path,
+			explicitConfigPath: input.config,
+			cwd
+		});
+		const modes = input.only.length === 0 ? /* @__PURE__ */ new Set([
+			"generated",
+			"index",
+			"log"
+		]) : new Set(input.only);
+		const result = yield* runSync({
+			bundleRoot: resolved.bundleRoot,
+			config: resolved.config,
+			modes,
+			dryRun: input.dryRun
+		}).pipe(Effect.provide(Layer.mergeAll(Git.layer, GitHistory.layer)));
+		const displayPath = displayRoot(cwd, result.bundleRoot, path);
+		if (input.format === "json") {
+			const envelope = syncEnvelope({
+				okfitVersion: CLI_VERSION,
+				root: displayPath,
+				dryRun: result.dryRun,
+				result
+			});
+			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
+	}));
+	if (input.format === "json") return yield* body.pipe(Effect.tapError((error) => Console.log(JSON.stringify(jsonError(error, CLI_VERSION)))));
+	return yield* body;
+})).pipe(Command.withDescription("Regenerate the derived-content families that no other command produces: generated.at, index.md, and log.md, all from git history and the bundle's own concepts. Mechanical and agent-runnable; never an attestation and never touches verified."));
+
+//#endregion
+export { syncCommand };

package/commands/validate.js

@@ -0,0 +1,98 @@
+import { provideConfig } from "../config/layer.js";
+import { resolveProjectConfig } from "../config/resolve.js";
+import { setExitCode } from "../internal/exit.js";
+import { forDiagnostics } from "../render/exit.js";
+import { collect } from "../render/sort.js";
+import { JsonEnvelope, json, jsonError } from "../render/json.js";
+import { CLI_VERSION } from "../version.js";
+import { useColor } from "../internal/tty.js";
+import { displayRoot, human, summary } from "../render/human.js";
+import { Now, run } from "../validate/run.js";
+import { Argument, Command, Flag } from "effect/unstable/cli";
+import { Console, Effect, Layer, Option, Path, Schema } from "effect";
+import { OKF_SPEC_VERSION } from "@okfit/core";
+import { GitHistory } from "@okfit/profiles";
+import { Git } from "@effected/git";
+
+//#region src/commands/validate.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"));
+/** 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"));
+/** K-6: `--format` is on `validate` only. */
+const formatFlag = Flag.choice("format", ["human", "json"]).pipe(Flag.withDefault("human"), Flag.withDescription("output format: human (default) or json"));
+/** S-31: skips `Provenance.lint`'s git tier for this invocation, without touching `[lint]`. */
+const skipProvenanceFlag = Flag.boolean("skip-provenance").pipe(Flag.withDefault(false), Flag.withDescription("skip the generated-at-drift lint's git tier for this run"));
+/**
+* `okfit validate [path] [--config <file>] [--format human|json] [--skip-provenance]`.
+*
+* Handler order fixed by the contract (§2 `src/commands/validate.ts`):
+* stat `--config` (K-1) via `provideConfig`, discover (`OkfitConfigFile.discover`),
+* resolve the profile with the K-4 warning, merge `DEFAULTS < profile < file`
+* (D-28), warn on an `okf_version` mismatch (K-15), resolve the project and
+* bundle roots (K-12), run (`validate/run.ts#run`), collect and sort the
+* diagnostics, render per `--format` (K-18, K-20 to K-22), and set the exit
+* code without failing the Effect (K-7, K-8).
+*
+* @public
+*/
+const validateCommand = Command.make("validate", {
+	path: pathArg,
+	config: configFlag,
+	format: formatFlag,
+	skipProvenance: skipProvenanceFlag
+}, (input) => Effect.gen(function* () {
+	const cwd = process.cwd();
+	const discoveryCwd = Option.getOrElse(input.path, () => cwd);
+	const now = yield* Now;
+	const path = yield* Path.Path;
+	const body = Effect.gen(function* () {
+		const { bundleRoot, config: merged, profile } = yield* resolveProjectConfig({
+			pathArg: input.path,
+			explicitConfigPath: input.config,
+			cwd
+		});
+		const result = yield* run({
+			root: bundleRoot,
+			config: merged,
+			profile,
+			now,
+			skipProvenance: input.skipProvenance
+		}).pipe(Effect.provide(Layer.mergeAll(Git.layer, GitHistory.layer)));
+		const diagnostics = collect(result.report.conformance, result.report.lint, result.profileDiagnostics);
+		const code = forDiagnostics(diagnostics);
+		if (input.format === "json") {
+			const envelope = json({
+				okfitVersion: CLI_VERSION,
+				okfVersion: merged.okf_version ?? OKF_SPEC_VERSION,
+				root: bundleRoot,
+				profile: Option.match(profile, {
+					onNone: () => null,
+					onSome: (p) => p.name
+				}),
+				exitCode: code,
+				concepts: result.bundle.concepts.size,
+				diagnostics
+			});
+			yield* Console.log(JSON.stringify(Schema.encodeSync(JsonEnvelope)(envelope)));
+		} else {
+			for (const diagnosticLine of human(diagnostics, { color: useColor() })) yield* Console.log(diagnosticLine);
+			const counts = {
+				errors: diagnostics.filter((d) => d.severity === "error").length,
+				warnings: diagnostics.filter((d) => d.severity === "warning").length,
+				info: diagnostics.filter((d) => d.severity === "info").length,
+				concepts: result.bundle.concepts.size
+			};
+			yield* Console.error(summary(counts, displayRoot(cwd, bundleRoot, path)));
+		}
+		setExitCode(code);
+	}).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)))));
+	return yield* body;
+})).pipe(Command.withDescription("Load config and bundle, run conformance and lint checks, and render the diagnostics."));
+
+//#endregion
+export { validateCommand };

package/commands/verify.js

@@ -0,0 +1,98 @@
+import { provideConfig } from "../config/layer.js";
+import { resolveProjectConfig } from "../config/resolve.js";
+import { setExitCode } from "../internal/exit.js";
+import { jsonError } from "../render/json.js";
+import { CLI_VERSION } from "../version.js";
+import { displayRoot } from "../render/human.js";
+import { Now } from "../validate/run.js";
+import { VerifyEnvelope, humanVerify, verifyEnvelope } from "../render/verify.js";
+import { runVerify } from "../verify/run.js";
+import { Argument, Command, Flag } from "effect/unstable/cli";
+import { Console, DateTime, Effect, Option, Path, Schema } from "effect";
+import { Timestamp } from "@okfit/core";
+import { Git } from "@effected/git";
+
+//#region src/commands/verify.ts
+/** V-6: tolerant id, normalised through `ConceptId.normalize`; never `Argument.path`. */
+const idArg = Argument.string("id").pipe(Argument.withDescription("concept id to verify, with or without a leading slash or trailing .md"));
+/** K-2: `[path]` is the PROJECT root, byte-identical to validate/init/context's. */
+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"));
+/** K-1: no `mustExist`; the handler stats it via `provideConfig`. */
+const configFlag = Flag.file("config").pipe(Flag.optional, Flag.withDescription("explicit config file; skips discovery"));
+/** V-6: `Flag.string`, decoded through core's `Timestamp` — never `Flag.date`, which yields a bare Date. */
+const atFlag = Flag.string("at").pipe(Flag.optional, Flag.withDescription("ISO 8601 timestamp with an explicit offset to record instead of now"));
+/** V-6/V-8: the preview is a flag, never a prompt. */
+const dryRunFlag = Flag.boolean("dry-run").pipe(Flag.withDefault(false), Flag.withDescription("print the exact fragment a real run would splice in; write nothing"));
+const formatFlag = Flag.choice("format", ["human", "json"]).pipe(Flag.withDefault("human"), Flag.withDescription("output format: human (default) or json"));
+/**
+* `okfit verify <id> [path] [--config <file>] [--at <iso>] [--dry-run]
+* [--format human|json]`.
+*
+* Handler order fixed by contract §2.3. Steps 1–3 are `context`'s handler
+* in substance — stat `--config` (K-1) via `provideConfig`, discover,
+* resolve the profile and roots through `resolveProjectConfig` — then it
+* diverges: resolve `at` (the `Now` service, or `--at` through
+* `Schema.decodeUnknownEffect(Timestamp)`, never the throwing sync
+* decoder), provide `Git` for `Derivation.generatedBy`, run the splice and
+* the atomic write, render, and always exit `0`. There is no content tier:
+* every typed failure is exit `3` through `bin.ts`'s existing
+* `reportFailures`.
+*
+* @public
+*/
+const verifyCommand = Command.make("verify", {
+	id: idArg,
+	path: pathArg,
+	config: configFlag,
+	at: atFlag,
+	dryRun: dryRunFlag,
+	format: formatFlag
+}, (input) => Effect.gen(function* () {
+	const cwd = process.cwd();
+	const discoveryCwd = Option.getOrElse(input.path, () => cwd);
+	const body = Effect.gen(function* () {
+		const path = yield* Path.Path;
+		const resolved = yield* resolveProjectConfig({
+			pathArg: input.path,
+			explicitConfigPath: input.config,
+			cwd
+		});
+		const at = Option.isNone(input.at) ? DateTime.startOf(yield* Now, "second") : yield* Schema.decodeUnknownEffect(Timestamp)(input.at.value);
+		const result = yield* runVerify({
+			id: input.id,
+			bundleRoot: resolved.bundleRoot,
+			projectRoot: resolved.projectRoot,
+			config: resolved.config,
+			at,
+			dryRun: input.dryRun
+		});
+		const displayPath = `${displayRoot(cwd, result.bundleRoot, path)}/${result.conceptPath}`;
+		if (input.format === "json") {
+			const envelope = verifyEnvelope({
+				okfitVersion: CLI_VERSION,
+				id: result.id,
+				path: displayPath,
+				by: result.by,
+				at: result.at,
+				dryRun: result.dryRun
+			});
+			yield* Console.log(JSON.stringify(Schema.encodeSync(VerifyEnvelope)(envelope)));
+		} else for (const line of humanVerify({
+			id: result.id,
+			by: result.by,
+			at: result.at,
+			priorAt: result.priorAt,
+			dryRun: result.dryRun,
+			fragment: result.fragment
+		})) yield* Console.log(line);
+		setExitCode(0);
+	}).pipe(Effect.provide(Git.layer), provideConfig({
+		explicitConfigPath: input.config,
+		discoveryCwd
+	}));
+	if (input.format === "json") return yield* body.pipe(Effect.tapError((error) => Console.log(JSON.stringify(jsonError(error, CLI_VERSION)))));
+	return yield* body;
+})).pipe(Command.withDescription("Record a human's attestation that a concept has been reviewed: append one verified entry, { by: human:<id>, at: <now> }, to its frontmatter. The actor is always your own git identity; there is no --by. This is a human-run command: no agent, hook, or MCP tool ever invokes it."));
+
+//#endregion
+export { verifyCommand };

package/config/anchor.js

@@ -0,0 +1,57 @@
+//#region src/config/anchor.ts
+/**
+* The explicit `--config` anchor rule (C-8): the parent of `.config` "if the
+* file sits in a `.config` directory, else the file's directory", with no
+* exception for a custom name. Upstream's `ConfigResolver.explicitPath`
+* reports no `dir` in its `match` by design, so this stays a hand-rolled,
+* basename-based rule rather than reading `ConfigMatch.dir` — the one
+* remaining path-tail string match in the CLI outside `init/scaffold.ts`
+* (C1-4).
+*/
+const anchorForExplicit = (configPath, path) => {
+	const parent = path.dirname(configPath);
+	return path.basename(parent) === ".config" ? path.dirname(parent) : parent;
+};
+/**
+* K-12's project root, as amended by K-58 and C1-2, in order:
+*
+* 1. `pathArg`, if given. `Argument.path` has already resolved it absolute.
+* 2. otherwise, if `--config` was given: `anchorForExplicit` applied to that
+*    path.
+* 3. otherwise, if a config was discovered by the `"project"` resolver
+*    (`ConfigResolver.upwardWalk`, named `"project"` in `layer.ts`) AND it
+*    reported a `dir`: that `dir` verbatim — it is already the ancestor
+*    `upwardWalk` anchored the match against (the parent of `.config` for a
+*    `.config/okfit.toml` candidate, the candidate's own directory
+*    otherwise), so no path-tail test is needed here any more.
+* 4. otherwise `cwd` — this covers every other resolver name (`"xdg"`,
+*    `"native"`, `"system"`) as defence in depth, a `"project"` match with no
+*    `dir` (should not happen, since `upwardWalk` always reports one), and
+*    no discovery at all.
+*
+* The CLI never probes for `.git` (K-12), even though
+* `ConfigResolver.gitRoot` exists.
+*
+* @public
+*/
+const resolveProjectRoot = (input) => {
+	if (input.pathArg._tag === "Some") return input.pathArg.value;
+	if (input.explicitConfigPath._tag === "Some") return anchorForExplicit(input.explicitConfigPath.value, input.path);
+	if (input.discovered._tag === "Some") {
+		const discovered = input.discovered.value;
+		if (discovered.resolver === "project" && discovered.dir !== void 0) return discovered.dir;
+	}
+	return input.cwd;
+};
+/**
+* `<project root>/<bundle.path>`, absolute (K-2). `config` is the MERGED
+* config, so `bundle.path` is `OkfitConfig.DEFAULTS.bundle.path` (`"okf"`)
+* unless a file or profile overrode it. The bundle root is never what
+* `[path]` names.
+*
+* @public
+*/
+const resolveBundleRoot = (projectRoot, config, path) => path.resolve(projectRoot, config.bundle?.path ?? "okf");
+
+//#endregion
+export { resolveBundleRoot, resolveProjectRoot };

package/config/layer.js

@@ -0,0 +1,129 @@
+import { ConfigMalformedError, ConfigPathNotFoundError } from "../errors.js";
+import { Cause, Effect, FileSystem, Option, Result } from "effect";
+import { AppConfig } from "@effected/app";
+import { ConfigCodecError, ConfigResolver, ConfigValidationError, MergeStrategy, TomlCodec } from "@effected/config-file";
+import { OkfitConfig, OkfitConfigFile } from "@okfit/core";
+
+//#region src/config/layer.ts
+/**
+* The `OkfitConfigFile` layer for one invocation (K-9 to K-11, K-57, C-6),
+* now one `AppConfig.layer(OkfitConfigFile, ...)` call in both branches; only
+* the chain options vary:
+*
+* - `explicitConfigPath` is `Some`: `resolvers: [ConfigResolver.explicitPath(path)]`
+*   and `xdg: false` — K-10's "only that path" rule, so the chain is exactly
+*   one resolver and no `systemEtc` tier is added either.
+* - `explicitConfigPath` is `None`: `resolvers: [ConfigResolver.upwardWalk({ filenames, ... })]`
+*   carrying C-1's three per-directory candidates (`.okfit.toml`,
+*   `okfit.toml`, `.config/okfit.toml`, directory-major so a child's later
+*   candidate beats a parent's earlier one — C-2's ascent to the filesystem
+*   root is `upwardWalk`'s own default with no `stopAt`), named `"project"`
+*   so `resolve.ts`/`anchor.ts` can identify it without string-matching a
+*   path tail. `systemEtc` is C-5's `/etc` tier, present unless
+*   `systemConfigDir` overrides its root (tests only — no production call
+*   site sets it). `xdg` and `native` stay on their defaults (C-4), which is
+*   what puts personal defaults at `$XDG_CONFIG_HOME/okfit/config.toml` and
+*   the native probe behind it.
+*
+* `filename: "config.toml"` is the same in both branches — it is the XDG/
+* native/system tiers' filename, unrelated to the C-1 project names above.
+* `defaultPath` is `AppConfig.layer`'s own `XdgConfig.savePath(filename)`, so
+* `save`/`update` do not fail with `ConfigDefaultPathMissingError`; nothing
+* here sets it explicitly any more.
+*
+* `discoveryCwd` is `[path]` when given, else `process.cwd()` (K-2), passed
+* straight through as `upwardWalk`'s own `cwd` so nothing in this module
+* reads the process.
+*
+* `App.layer`, `AppStore` and `AppCache` appear nowhere, so no
+* `store.db`/`cache.db` is ever created (K-9).
+*
+* @public
+*/
+const buildConfigLayer = (options) => Option.isSome(options.explicitConfigPath) ? AppConfig.layer(OkfitConfigFile, {
+	filename: "config.toml",
+	schema: OkfitConfig,
+	codec: TomlCodec,
+	strategy: MergeStrategy.firstMatch(),
+	resolvers: [ConfigResolver.explicitPath(options.explicitConfigPath.value)],
+	xdg: false
+}) : AppConfig.layer(OkfitConfigFile, {
+	filename: "config.toml",
+	schema: OkfitConfig,
+	codec: TomlCodec,
+	strategy: MergeStrategy.firstMatch(),
+	resolvers: [ConfigResolver.upwardWalk({
+		filenames: [
+			".okfit.toml",
+			"okfit.toml",
+			".config/okfit.toml"
+		],
+		cwd: options.discoveryCwd,
+		name: "project"
+	})],
+	systemEtc: options.systemConfigDir === void 0 ? true : { dir: options.systemConfigDir }
+});
+/**
+* The K-1 pre-flight and the provide, in that order and in one place: stat
+* `explicitConfigPath` with `FileSystem.exists` and fail with
+* `ConfigPathNotFoundError` BEFORE `buildConfigLayer` is called at all. This
+* is why the CLI does not use `Command.provide(cmd, (input) => layer)`,
+* which would construct the layer first (Judge notes 9) — here the stat
+* runs as the first step of one `Effect.gen`, and `buildConfigLayer` is only
+* reached, and only then actually run, on the step after it.
+*
+* `FileSystem.FileSystem.exists` is `(path: string) => Effect.Effect<boolean, PlatformError>`
+* (`EF/FileSystem.ts:143-145`), not infallible, so
+* `PlatformError.PlatformError` joins the error channel here (decision 7):
+* an unusual stat failure (e.g. a permission error on a parent directory)
+* renders through `renderFailure`'s catch-all rule rather than being
+* uncatchable by the type checker.
+*
+* K-46/K-63 fix: a `ConfigCodecError`/`ConfigValidationError` from
+* `buildConfigLayer`'s provided layer is wrapped into `ConfigMalformedError`
+* whenever the failing path is known, so `renderFailure` can name it:
+*
+* - `ConfigCodecError` now carries its own `path: string | undefined`
+*   (config-file 0.7.0, `ConfigFile.discover` re-raises with `path` attached
+*   at every site that fed the codec a path it resolved) — used when
+*   present, so a malformed file found during DISCOVERY (no `--config`) now
+*   also wraps into `ConfigMalformedError` naming the candidate that failed,
+*   closing the K-63 gap. It falls back to `explicitConfigPath` only when
+*   the library's own `path` is `undefined` and `--config` was given; only
+*   when neither is known does the cause pass through unwrapped.
+* - `ConfigValidationError` carries its own `path: Option<string>` — used
+*   when present (either branch), falling back to `explicitConfigPath` when
+*   the library's own `path` is `None` and `--config` was given.
+*
+* @public
+*/
+const provideConfig = (options) => (effect) => Effect.gen(function* () {
+	if (Option.isSome(options.explicitConfigPath)) {
+		const path = options.explicitConfigPath.value;
+		if (!(yield* (yield* FileSystem.FileSystem).exists(path))) return yield* Effect.fail(new ConfigPathNotFoundError({ path }));
+	}
+	return yield* effect.pipe(Effect.provide(buildConfigLayer(options)), Effect.catchCause((cause) => {
+		const found = Cause.findFail(cause);
+		if (Result.isSuccess(found)) {
+			const error = found.success.error;
+			if (error instanceof ConfigCodecError) {
+				const path = error.path !== void 0 ? error.path : Option.isSome(options.explicitConfigPath) ? options.explicitConfigPath.value : void 0;
+				if (path !== void 0) return Effect.fail(new ConfigMalformedError({
+					path,
+					cause: error
+				}));
+			}
+			if (error instanceof ConfigValidationError) {
+				const path = Option.isSome(options.explicitConfigPath) ? options.explicitConfigPath : error.path;
+				if (Option.isSome(path)) return Effect.fail(new ConfigMalformedError({
+					path: path.value,
+					cause: error
+				}));
+			}
+		}
+		return Effect.failCause(cause);
+	}));
+});
+
+//#endregion
+export { buildConfigLayer, provideConfig };

package/config/resolve.js

@@ -0,0 +1,67 @@
+import { resolveBundleRoot, resolveProjectRoot } from "./anchor.js";
+import { Console, Effect, Option, Path } from "effect";
+import { OKF_SPEC_VERSION, OkfitConfig, OkfitConfigFile } from "@okfit/core";
+import { Profiles } from "@okfit/profiles";
+
+//#region src/config/resolve.ts
+/**
+* `OkfitConfig.DEFAULTS.bundle.profile` is `"software-project"` at runtime
+* (the frozen literal always sets it), but `bundle` and `profile` are both
+* `optionalKey` in the schema, so the type checker sees `string | undefined`
+* two levels deep. The `?? "software-project"` fallback here is unreachable
+* in practice; it exists only to satisfy `noUncheckedIndexedAccess`-style
+* strictness without a non-null assertion. Formerly duplicated identically
+* in `commands/validate.ts` and `commands/context.ts`; this is its one home
+* now that both commands delegate to {@link resolveProjectConfig}.
+*
+* @public
+*/
+const DEFAULT_PROFILE_NAME = OkfitConfig.DEFAULTS.bundle?.profile ?? "software-project";
+/**
+* The config-resolution step byte-identical between `validate` and
+* `context`'s handlers (A2 review finding): discover, pick `sources[0]`,
+* default `{ extensions: {} }`, resolve the profile name and the K-4
+* unknown-profile warning, merge `DEFAULTS < profile < file` (D-28), warn on
+* an `okf_version` mismatch (K-15), then resolve the project and bundle
+* roots (K-12). Every message string and the merge order are unchanged from
+* the two commands' former inline copies.
+*
+* @public
+*/
+const resolveProjectConfig = (input) => Effect.gen(function* () {
+	const path = yield* Path.Path;
+	const discoveredSource = (yield* (yield* OkfitConfigFile).discover)[0];
+	const fileConfig = discoveredSource === void 0 ? { extensions: {} } : discoveredSource.value;
+	const profileName = fileConfig.bundle?.profile ?? DEFAULT_PROFILE_NAME;
+	const profile = profileName === "none" ? Option.none() : Profiles.get(profileName);
+	if (profileName !== "none" && Option.isNone(profile)) yield* Console.error(`warning: unknown profile "${profileName}"; continuing with defaults`);
+	const base = Option.match(profile, {
+		onNone: () => OkfitConfig.DEFAULTS,
+		onSome: (p) => OkfitConfig.merge(OkfitConfig.DEFAULTS, p.config)
+	});
+	const merged = OkfitConfig.merge(base, fileConfig);
+	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 discovered = discoveredSource === void 0 ? Option.none() : Option.some({
+		path: discoveredSource.path,
+		resolver: discoveredSource.resolver,
+		...discoveredSource.match?.dir !== void 0 ? { dir: discoveredSource.match.dir } : {}
+	});
+	const projectRoot = resolveProjectRoot({
+		pathArg: input.pathArg,
+		explicitConfigPath: input.explicitConfigPath,
+		discovered,
+		cwd: input.cwd,
+		path
+	});
+	return {
+		projectRoot,
+		bundleRoot: resolveBundleRoot(projectRoot, merged, path),
+		config: merged,
+		profile,
+		profileName,
+		discovered
+	};
+});
+
+//#endregion
+export { DEFAULT_PROFILE_NAME, resolveProjectConfig };

package/context/run.js

@@ -0,0 +1,35 @@
+import { Effect, FileSystem, Path } from "effect";
+
+//#region src/context/run.ts
+/**
+* The whole of `context`'s filesystem work: join `index.md` onto the bundle
+* root and stat it. Loading a bundle and running conformance/lint checks
+* over it never happen here — that is what makes `context` cheap enough
+* for a hook to run on every session start and every in-bundle write
+* (M-15).
+*
+* `"index.md"` is a literal here, not read from the profile's layout: the
+* spec fixes the reserved filename regardless of profile, and a
+* profile-less merge (`profile = "none"`) has no layout to read from at
+* all — `context` behaves identically with and without a profile.
+*
+* `exists` is `(path) => Effect.Effect<boolean, PlatformError>`, so an
+* unreadable parent directory would otherwise fail the command; here it is
+* absorbed to `false`, because "the hook could not stat index.md" and
+* "index.md is not there" are the same fact from a consumer's point of
+* view.
+*
+* @public
+*/
+const runContext = (options) => Effect.gen(function* () {
+	const path = yield* Path.Path;
+	const fs = yield* FileSystem.FileSystem;
+	const indexPath = path.join(options.bundleRoot, "index.md");
+	return {
+		indexPath,
+		indexExists: yield* fs.exists(indexPath).pipe(Effect.orElseSucceed(() => false))
+	};
+});
+
+//#endregion
+export { runContext };