@okfit/cli 0.1.0 → 0.2.0

package/index.d.ts

@@ -1,19 +1,904 @@
+import { ConfigReadError, ConfigReadError as ConfigReadError$1 } from "@effected/config-file";
+import { Context, DateTime, Effect, FileSystem, Layer, Option, Path, PlatformError, Runtime, Schema } from "effect";
+import { Git, GitCommandError, UnknownRefError } from "@effected/git";
+import { BundleLoadError, Diagnostic, DiagnosticRange, DiagnosticSeverity, LoadedBundle, OkfitConfig, OkfitConfigFile, ValidationReport } from "@okfit/core";
+import { GitHistory, GitHistoryError, Layout, Profile, ProfileDiagnostic } from "@okfit/profiles";
 import { Command } from "effect/unstable/cli";
+import { AppDirs, Xdg } from "@effected/xdg";
+import { FrontmatterWriteError, MarkdownParseError } from "@effected/markdown";
+//#region src/errors.d.ts
+declare const ConfigPathNotFoundError_base: Schema.Class<ConfigPathNotFoundError, Schema.TaggedStruct<"ConfigPathNotFoundError", {
+  readonly path: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * `--config <path>` named a path that does not exist. Every `ConfigResolver`
+ * has a `never` error channel and `explicitPath` absorbs a missing target
+ * into `Option.none()`, so a bad `--config` would otherwise fall through to
+ * the XDG file silently. The CLI checks it itself before building any layer
+ * (K-1, spec 4.1).
+ *
+ * @public
+ */
+export declare class ConfigPathNotFoundError extends ConfigPathNotFoundError_base {
+  readonly [Runtime.errorExitCode] = 3;
+  get message(): string;
+}
+declare const InitOverwriteError_base: Schema.Class<InitOverwriteError, Schema.TaggedStruct<"InitOverwriteError", {
+  readonly paths: Schema.$Array<Schema.String>;
+  readonly cwd: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * `okfit init` found one or more of its target paths already present (K-28).
+ * Carries the whole conflicting-path list so the renderer prints every one.
+ * `paths` are absolute; `renderFailure` relativises them to `cwd` (K-51).
+ *
+ * @public
+ */
+export declare class InitOverwriteError extends InitOverwriteError_base {
+  readonly [Runtime.errorExitCode] = 3;
+  get message(): string;
+}
+declare const VerifyConceptNotFoundError_base: Schema.Class<VerifyConceptNotFoundError, Schema.TaggedStruct<"VerifyConceptNotFoundError", {
+  readonly id: Schema.String;
+  readonly root: Schema.String;
+  readonly reason: Schema.Literals<readonly ["not-a-concept", "reserved", "undecodable"]>;
+  readonly diagnosticCode: Schema.optionalKey<Schema.String>;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * V-9: `<id>` did not resolve to a verifiable concept. `reason` is
+ * `"not-a-concept"` (no such file, or an id that normalises to nothing),
+ * `"reserved"` (the id names `index.md` or `log.md`), or `"undecodable"`
+ * (a file exists but `bundle.diagnostics` names it — `diagnosticCode`
+ * carries which). `root` is the absolute bundle root, kept OFF `message`
+ * so K-51's relativisation rule has nothing to apply to and the human
+ * line and the JSON envelope's `message` are identical.
+ *
+ * @public
+ */
+export declare class VerifyConceptNotFoundError extends VerifyConceptNotFoundError_base {
+  readonly [Runtime.errorExitCode] = 3;
+  get message(): string;
+}
+declare const VerifyUnsupportedFrontmatterError_base: Schema.Class<VerifyUnsupportedFrontmatterError, Schema.TaggedStruct<"VerifyUnsupportedFrontmatterError", {
+  readonly id: Schema.String;
+  readonly shape: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * V-14: fail closed on a `verified` shape the classifier does not name.
+ * `shape` is one of `"alias"`, `"merge-key"`, `"scalar"`, `"empty"` (and,
+ * defensively, `"no-frontmatter"` or `"not-a-mapping"`, neither reachable
+ * for a concept that reached `bundle.concepts`). The file is never opened
+ * for writing when this is raised.
+ *
+ * @public
+ */
+export declare class VerifyUnsupportedFrontmatterError extends VerifyUnsupportedFrontmatterError_base {
+  readonly [Runtime.errorExitCode] = 3;
+  get message(): string;
+}
+declare const ConfigMalformedError_base: Schema.Class<ConfigMalformedError, Schema.TaggedStruct<"ConfigMalformedError", {
+  readonly path: Schema.String;
+  readonly cause: Schema.Defect;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * A config file at a KNOWN path failed to parse or validate (K-46's own
+ * intent — "each class' message already names the offending path" does not
+ * hold for `@effected/config-file`'s `ConfigCodecError`, which carries no
+ * `path` field at all; this wraps it, and `ConfigValidationError`, with the
+ * path the caller already knows). `cause` is the original config-file error,
+ * preserved structurally, never stringified early.
+ *
+ * @public
+ */
+export declare class ConfigMalformedError extends ConfigMalformedError_base {
+  readonly [Runtime.errorExitCode] = 3;
+  get message(): string;
+}
+/**
+ * The `render` option for `CliRuntime.reportFailures` (K-30, K-46, K-51). One
+ * string per stderr line; `reportFailures` emits each through its own
+ * `Effect.logError`, which `CliLogger` routes to stderr.
+ *
+ * Rules, in order:
+ *
+ * 1. A `ShowHelp` (any `_tag === "ShowHelp"`) renders as `[]` — the empty
+ *    array. `Command.runWith` has already rendered the help document and any
+ *    parse errors before re-failing, so a second rendering here would print
+ *    "Help requested" after the help text. This is why the K-30 remap in
+ *    `bin.ts` can run ahead of `reportFailures` without corrupting `--help`
+ *    output.
+ * 2. `ConfigPathNotFoundError` renders as its own `error: <message>` line;
+ *    `InitOverwriteError` renders as the K-51 header, one two-space-indented
+ *    relativised path per conflict, and the literal `Nothing was written.`.
+ * 3. `ConfigMalformedError` renders as its own `error: <message>` line —
+ *    `error: malformed config <path>: <cause message>` — since it already
+ *    carries the offending path (`config/layer.ts#provideConfig` wraps a
+ *    `ConfigCodecError`/`ConfigValidationError` into this the moment the
+ *    path is known).
+ * 4. A `ConfigValidationError` NOT already wrapped above (detected by
+ *    `_tag`, since the peer is optional and this module keeps it a
+ *    type-only import — this is the "path unknown" case, K-46) renders as
+ *    `error: ${String(error)}` followed by one two-space-indented
+ *    `ConfigIssueRenderer.render(error)` line per entry.
+ * 5. `VerifyConceptNotFoundError` and `VerifyUnsupportedFrontmatterError`
+ *    each render as their own `error: <message>` line; both messages
+ *    already name the concept id and what to do about it, and neither
+ *    carries a filesystem path needing K-51 relativisation.
+ * 6. Everything else — core's `BundleRootNotFoundError`/`BundleReadError`/
+ *    `BundleDepthExceededError`, config-file's other errors, `XdgEnvError`
+ *    (the K-13 `HOME`-unset case) — renders as the single line
+ *    `error: ${String(error)}`. Each of those
+ *    classes' own `message` already names the offending path, which is all
+ *    K-46 asserts.
+ *
+ * @public
+ */
+export declare const renderFailure: (error: unknown) => ReadonlyArray<string>;
+//#endregion
+//#region src/validate/run.d.ts
+declare const Now_base: Context.ServiceClass<Now, "@okfit/cli/Now", DateTime.Utc>;
+/**
+ * K-47's ambient clock. `bin.ts` resolves `OKFIT_NOW` (or the wall clock)
+ * exactly once and provides it with `Effect.provideService(Now, value)`
+ * around the whole command tree; `commands/validate.ts` and
+ * `commands/init.ts` each read it with `const now = yield* Now;` before
+ * building {@link RunOptions} or a scaffold's `today`. Not re-exported from
+ * `index.ts`: like `internal/exit.ts` and `internal/tty.ts`, it means
+ * nothing outside a spawned process (K-49). `Context.Tag` does not exist on
+ * the Effect v4 line; the v4 shape is
+ * `Context.Service<Self, Shape>()(id)`, the same form core and profiles use
+ * for their own services (`PROFILES/GitHistory.ts:140`) — source wins over
+ * the contract's literal snippet here (K-62).
+ *
+ * @internal
+ */
+declare class Now extends Now_base {}
+/** @public */
+interface RunOptions {
+  /** Absolute bundle root; `Bundle.load` never reads cwd (D-8). */
+  readonly root: string;
+  /** Already merged `DEFAULTS < profile < file` by the caller (D-28). */
+  readonly config: OkfitConfig;
+  /** The resolved profile, when `Profiles.get` found one. */
+  readonly profile: Option.Option<Profile>;
+  /** `OKFIT_NOW` or `DateTime.now`, from `bin.ts` (K-47); enables the `stale` rule (D-34). */
+  readonly now: DateTime.Utc;
+  /**
+   * S-31: skip `Provenance.lint`'s git tier for this one invocation,
+   * without touching the project's `[lint]` table. `commands/validate.ts`
+   * threads `--skip-provenance` here; the PostToolUse hook passes the flag
+   * so an edit-time `validate` stays git-free even when the config leaves
+   * `generated-at-drift` at its default severity. Defaults to `false`, and
+   * is checked the same way `severity === "off"` already is — `run` skips
+   * the walk when EITHER is true.
+   */
+  readonly skipProvenance?: boolean;
+}
+/** @public */
+interface RunResult {
+  readonly bundle: LoadedBundle;
+  readonly report: ValidationReport;
+  /** `[]` when `profile` is `None`. */
+  readonly profileDiagnostics: ReadonlyArray<ProfileDiagnostic>;
+}
+/**
+ * Load, validate both tiers, run the profile check, then — UNLESS the
+ * `generated-at-drift` lint is `off` OR `options.skipProvenance` is `true`
+ * — run `Provenance.lint` and append its `Diagnostic`s to `report.lint`.
+ * The "skip the git walk entirely" gate lives HERE, in `run`, not inside
+ * `Provenance.lint` (S-8's own wording): a bundle configured `off`, or a
+ * caller that passed `--skip-provenance`, never pays for a git spawn
+ * (S-31). An `error` severity on the appended diagnostics yields exit `1`
+ * through the EXISTING lint-tier rule in `render/exit.ts` — no renderer
+ * branch, no new `DiagnosticSource`, since these diagnostics flow through
+ * the same `report.lint` array every other core lint diagnostic already
+ * does.
+ *
+ * K-52 holds structurally: `Bundle.load`'s failure short-circuits the
+ * generator, so `profile.check` never runs on a bundle that did not load.
+ *
+ * This is a BREAKING signature change: `@okfit/mcp`'s `validateBundle.ts`
+ * calls this function directly and must be updated to match (Task C1);
+ * `commands/validate.ts` is the other caller.
+ *
+ * @public
+ */
+export declare const run: (options: RunOptions) => Effect.Effect<RunResult, BundleLoadError | GitHistoryError | GitCommandError | UnknownRefError | PlatformError.PlatformError, FileSystem.FileSystem | Path.Path | Git | GitHistory>;
+//#endregion
 //#region src/commands/root.d.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
+ */
+export declare const rootCommand: Command.Command<"okfit", {} | {}, {}, import("@okfit/profiles").AgentActorUnconfiguredError | import("@okfit/core").BundleDepthExceededError | import("@okfit/core").BundleReadError | import("@okfit/core").BundleRootNotFoundError | import("@effected/config-file").ConfigCodecError | import("@effected/config-file").ConfigFileReadError | ConfigMalformedError | ConfigPathNotFoundError | import("@effected/config-file").ConfigValidationError | import("@effected/markdown").FrontmatterEncodeError | import("@effected/markdown").FrontmatterFormatMismatchError | import("@effected/markdown").FrontmatterValidationError | import("@effected/git").GitCommandError | import("@okfit/profiles").GitHistoryError | import("@okfit/profiles").HumanActorUnresolvedError | InitOverwriteError | import("@effected/markdown").MarkdownParseError | import("@effected/git").NotARepositoryError | import("effect/PlatformError").PlatformError | import("effect/Schema").SchemaError | import("@effected/git").UnknownRefError | VerifyConceptNotFoundError | VerifyUnsupportedFrontmatterError | import("@effected/yaml").YamlParseError, import("@effected/xdg").AppDirs | import("effect/unstable/process/ChildProcessSpawner").ChildProcessSpawner | import("effect/FileSystem").FileSystem | Now | import("effect/Path").Path | import("@effected/xdg").Xdg>;
+//#endregion
+//#region src/config/anchor.d.ts
+/**
+ * What {@link resolveProjectRoot} needs about the winning discovery source
+ * (K-12, K-58). Narrower than `@effected/config-file`'s own
+ * `ConfigSource`: only `path`, `resolver` and the match's `dir` matter for
+ * anchoring, and a caller building this from a real
+ * `ConfigSource<OkfitConfig>` simply drops `value`.
+ *
+ * @public
+ */
+interface DiscoveredConfig {
+  /** `ConfigSource.path` — absolute. */
+  readonly path: string;
+  /** `ConfigSource.resolver` — the resolver's `name`. */
+  readonly resolver: string;
+  /**
+   * `ConfigSource.match?.dir` — the ancestor directory `upwardWalk`
+   * anchored the winning candidate against. Absent when the resolver did
+   * not implement `resolveMatch`, or reported no `dir` (`explicitPath`
+   * never does, by design).
+   */
+  readonly dir?: string;
+}
+/**
+ * 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
+ */
+export declare const resolveProjectRoot: (input: {
+  readonly pathArg: Option.Option<string>;
+  readonly explicitConfigPath: Option.Option<string>;
+  readonly discovered: Option.Option<DiscoveredConfig>;
+  readonly cwd: string;
+  readonly path: Path.Path;
+}) => string;
+/**
+ * `<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
+ */
+export declare const resolveBundleRoot: (projectRoot: string, config: OkfitConfig, path: Path.Path) => string;
+//#endregion
+//#region src/config/layer.d.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
+ */
+export declare const buildConfigLayer: (options: {
+  readonly explicitConfigPath: Option.Option<string>;
+  readonly discoveryCwd: string;
+  /**
+   * System config root, defaulting to `/etc`. Overridable primarily so tests
+   * can point at a writable temp directory — the real `/etc` is not writable
+   * in test environments. No production call site sets it.
+   */
+  readonly systemConfigDir?: string;
+}) => Layer.Layer<OkfitConfigFile, never, FileSystem.FileSystem | Path.Path | AppDirs | Xdg>;
+/**
+ * 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
+ */
+export declare const provideConfig: (options: {
+  readonly explicitConfigPath: Option.Option<string>;
+  readonly discoveryCwd: string;
+  readonly systemConfigDir?: string;
+}) => <A, E, R>(effect: Effect.Effect<A, E, R>) => Effect.Effect<A, E | ConfigPathNotFoundError | ConfigMalformedError | PlatformError.PlatformError, Exclude<R, OkfitConfigFile> | FileSystem.FileSystem | Path.Path | AppDirs | Xdg>;
+//#endregion
+//#region src/config/resolve.d.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
+ */
+export declare const DEFAULT_PROFILE_NAME: string;
+/**
+ * Everything `validate` and `context`'s handlers derive from config
+ * discovery before diverging (contract §8.3): the merged config, the
+ * resolved profile (and its name after the "none"/default rule), the
+ * discovery source (if any), and the project/bundle roots.
+ *
+ * @public
+ */
+interface ResolvedProjectConfig {
+  readonly projectRoot: string;
+  readonly bundleRoot: string;
+  readonly config: OkfitConfig;
+  readonly profile: Option.Option<Profile>;
+  readonly profileName: string;
+  readonly discovered: Option.Option<DiscoveredConfig>;
+}
+/**
+ * Input to {@link resolveProjectConfig}: the same three values every command
+ * handler already has in hand (its own `[path]` argument, its own
+ * `--config` flag, and `process.cwd()`) — nothing this function needs is
+ * read from `process` itself.
+ *
+ * @public
+ */
+interface ResolveProjectConfigInput {
+  readonly pathArg: Option.Option<string>;
+  readonly explicitConfigPath: Option.Option<string>;
+  readonly cwd: string;
+}
+/**
+ * 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
+ */
+export declare const resolveProjectConfig: (input: ResolveProjectConfigInput) => Effect.Effect<ResolvedProjectConfig, ConfigReadError$1, OkfitConfigFile | Path.Path>;
+//#endregion
+//#region src/context/run.d.ts
+/** @public */
+interface ContextRunOptions {
+  readonly bundleRoot: string;
+}
+/** @public */
+interface ContextResult {
+  readonly indexPath: string;
+  readonly indexExists: boolean;
+}
+/**
+ * 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
+ */
+export declare const runContext: (options: ContextRunOptions) => Effect.Effect<ContextResult, never, FileSystem.FileSystem | Path.Path>;
+//#endregion
+//#region src/init/scaffold.d.ts
+/** `.config/okfit.toml`, relative to the project root (C-10). @public */
+export declare const CONFIG_RELATIVE_PATH = ".config/okfit.toml";
+/** @public */
+interface ScaffoldOptions {
+  /** Absolute. */
+  readonly projectRoot: string;
+  /** Absolute; `<projectRoot>/<bundle.path>`. */
+  readonly bundleRoot: string;
+  /** The resolved profile's `layout` (`PROFILES/Profile.ts:35-38`, P-26). */
+  readonly layout: Layout;
+  /** The name written into the config and the log entry. */
+  readonly profileName: string;
+  /** `basename(projectRoot)` — `project.md`'s `title` (K-26). */
+  readonly projectTitle: string;
+  /** `YYYY-MM-DD`, derived from the CLI's `now` (K-25, K-47). */
+  readonly today: string;
+}
+/** One file `init` will write. Pure data; this module imports no `FileSystem`. @public */
+interface ScaffoldFile {
+  /** Absolute. */
+  readonly path: string;
+  readonly contents: string;
+}
+/**
+ * K-23: the THIN override only — never the merged config. `bundle.path` is
+ * the bundle root relative to the project root; `extensions: {}` satisfies
+ * `OkfitConfig`'s one non-optional field (`CORE/OkfitConfig.ts:164`).
+ * Everything else resolves from `DEFAULTS` and the profile at load time.
+ * `actors.agent` is deliberately absent (K-24, P-17).
+ *
+ * @public
+ */
+export declare const configValue: (options: ScaffoldOptions & {
+  readonly bundlePath: string;
+}) => OkfitConfig;
+/**
+ * Every path `init` will create, absolute, in write order, for the K-28
+ * pre-flight: the three project-level config names, the bundle root's
+ * `index.md`/`log.md`/`project.md`, then one `index.md` per layout directory
+ * in `layout`'s own declared order — never re-sorted here. `Derive.renderIndex`
+ * sorts its own `Subdirectories` section independently (C13), so this
+ * function's order has no bearing on the rendered index text.
+ *
+ * @public
+ */
+export declare const targetPaths: (options: ScaffoldOptions) => ReadonlyArray<string>;
+/**
+ * The three root markdown files and the per-directory indexes (K-25 to
+ * K-27, K-59). `project.md`'s frontmatter is written with
+ * `MarkdownFrontmatter.setToString` — the INSERT path, since the body below
+ * carries no frontmatter block of its own (`MD/index.d.ts:1959`,
+ * `FrontmatterWriteError`'s own doc comment: "a document with no frontmatter
+ * capture is the insert path, not an error"). The root `index.md` is
+ * `Derive.renderIndex` over a `LoadedConcept` this function synthesizes from
+ * the just-rendered `project.md` text, re-parsed with `MarkdownDocument.parse`
+ * (K-59; `renderIndex` reads only `frontmatter.type`/`title`/`description`
+ * and `path`, never `document`, `CORE/Derive.ts:75-101`, so the synthesized
+ * value is faithful). Each per-directory `index.md` is the literal
+ * `# <Directory>` — NOT `Derive.renderIndex`, which returns the empty string
+ * for an empty concept list with no options (contract Judge notes item 2).
+ *
+ * @public
+ */
+export declare const files: (options: ScaffoldOptions) => Effect.Effect<ReadonlyArray<ScaffoldFile>, MarkdownParseError | FrontmatterWriteError>;
+//#endregion
+//#region src/render/context.d.ts
+/** One `types[]` entry (M-15). @public */
+export declare const ContextType: Schema.Struct<{
+  readonly name: Schema.String;
+  readonly description: Schema.NullOr<Schema.String>;
+  readonly guidance: Schema.NullOr<Schema.String>;
+}>;
+/** @public */
+export type ContextType = typeof ContextType.Type;
+/** One `tags[]` entry (M-15). @public */
+export declare const ContextTag: Schema.Struct<{
+  readonly name: Schema.String;
+  readonly description: Schema.NullOr<Schema.String>;
+}>;
+/** @public */
+export type ContextTag = typeof ContextTag.Type;
+/**
+ * M-15's envelope: schema 1, snake_case, orientation data only. Distinct
+ * from `JsonEnvelope` (`render/json.ts`) — `context` never runs conformance
+ * or lint checks, so there is no `diagnostics` array and no `exit_code`
+ * field at all.
+ *
+ * Every field is `Schema.NullOr`, never `Schema.optionalKey`: a consumer
+ * (the two hook scripts) reads a fixed key set and gets JSON `null` for an
+ * absent value, rather than having to distinguish a missing key from a
+ * null one. This is a deliberate difference from `JsonDiagnostic`'s
+ * `range`, which is `optionalKey` and omitted when absent
+ * (`render/json.ts:14,68`).
+ *
+ * `profile_requested` (final-review Important 1) is the profile name the
+ * config asked for after the K-4 default rule — `resolveProjectConfig`'s
+ * own `profileName` — and is `null` only when no config file was found at
+ * all. `profile` keeps its original meaning (the resolved profile's name,
+ * or `null` when the requested name is unknown or `"none"`). The two
+ * differ exactly when a config named an unrecognised profile: `profile`
+ * is `null` but `profile_requested` still names what was asked for, so a
+ * consumer can tell "no profile configured" apart from "an unknown profile
+ * was configured".
+ *
+ * @public
+ */
+export declare const ContextEnvelope: Schema.Struct<{
+  readonly schema: Schema.Literal<1>;
+  readonly project_root: Schema.String;
+  readonly bundle_root: Schema.String;
+  readonly config_path: Schema.NullOr<Schema.String>;
+  readonly profile: Schema.NullOr<Schema.String>;
+  readonly profile_requested: Schema.NullOr<Schema.String>;
+  readonly index_path: Schema.String;
+  readonly index_exists: Schema.Boolean;
+  readonly actors: Schema.Struct<{
+    readonly agent: Schema.NullOr<Schema.String>;
+  }>;
+  readonly types: Schema.$Array<Schema.Struct<{
+    readonly name: Schema.String;
+    readonly description: Schema.NullOr<Schema.String>;
+    readonly guidance: Schema.NullOr<Schema.String>;
+  }>>;
+  readonly tags: Schema.$Array<Schema.Struct<{
+    readonly name: Schema.String;
+    readonly description: Schema.NullOr<Schema.String>;
+  }>>;
+}>;
+/** @public */
+export type ContextEnvelope = typeof ContextEnvelope.Type;
+/**
+ * Build the envelope from the merged config. `types`/`tags` sort by `name`
+ * with plain code-unit comparison, never locale-dependent — the same rule
+ * `render/sort.ts`'s K-17 comparator and
+ * `packages/profiles/src/SoftwareProject.ts:119`'s own sort use.
+ *
+ * @public
+ */
+export declare const contextEnvelope: (input: {
+  readonly projectRoot: string;
+  readonly bundleRoot: string;
+  readonly configPath: string | null;
+  readonly profile: string | null;
+  readonly profileRequested: string | null;
+  readonly indexPath: string;
+  readonly indexExists: boolean;
+  readonly config: OkfitConfig;
+}) => ContextEnvelope;
+/**
+ * The `human` format: a short header block, then one line per type and one
+ * per tag. Pure; the caller pipes each line through `Console.log`.
+ *
+ * The `profile:` line reads `profile: (none) (requested NAME, unknown)`
+ * when `profile` and `profile_requested` disagree over an actually-unknown
+ * profile — never for the `"none"` or no-config cases, where a `null`
+ * `profile` is expected, not an error.
+ *
+ * @public
+ */
+export declare const humanContext: (envelope: ContextEnvelope) => ReadonlyArray<string>;
+//#endregion
+//#region src/render/sort.d.ts
+/** Which producer a diagnostic came from; the JSON envelope's `source` (K-21). @public */
+type DiagnosticSource = "core.conformance" | "core.lint" | "profile";
+/**
+ * The one shape both renderers consume. `file` is the bundle-relative posix
+ * path core produced, `""` for a bundle-level finding. `range` is core's own
+ * zero-based `DiagnosticRange` instance, passed through untouched (K-21).
+ * `code` is widened to `string`: core's `DiagnosticCode`
+ * (`CORE/Diagnostic.ts:45-46`) and profiles' `ProfileDiagnosticCode`
+ * (`PROFILES/Profile.ts:47`) are disjoint closed unions and this carries
+ * either.
+ *
+ * @public
+ */
+interface RenderedDiagnostic {
+  readonly source: DiagnosticSource;
+  readonly file: string;
+  readonly range?: DiagnosticRange;
+  readonly code: string;
+  readonly severity: DiagnosticSeverity;
+  readonly message: string;
+}
+/**
+ * Tag core's two arrays and profiles' one, in producer order. Not named
+ * `merge`: `OkfitConfig.merge` already owns that word in this codebase.
+ *
+ * @public
+ */
+export declare const collect: (conformance: ReadonlyArray<Diagnostic>, lint: ReadonlyArray<Diagnostic>, profile: ReadonlyArray<ProfileDiagnostic>) => ReadonlyArray<RenderedDiagnostic>;
+/**
+ * K-17: `file` ascending (so `""` — the bundle-level finding — leads), then
+ * range-less before ranged within a file, then `range.offset` ascending, then
+ * `code`. Plain code-unit comparison, never locale-dependent (the same rule
+ * profiles' own `check` sorts by, `PROFILES/SoftwareProject.ts:119`). Stable:
+ * implemented with `toSorted`, which is specified as stable.
+ *
+ * @public
+ */
+export declare const sort: (diagnostics: ReadonlyArray<RenderedDiagnostic>) => ReadonlyArray<RenderedDiagnostic>;
+//#endregion
+//#region src/render/exit.d.ts
+/** @public */
+interface Tally {
+  readonly conformanceErrors: number;
+  readonly lintErrors: number;
+  readonly lintWarnings: number;
+  readonly lintInfo: number;
+  readonly profileErrors: number;
+}
+/**
+ * One pass over the collected diagnostics. `core.conformance` entries are
+ * always severity `error` (D-33); the counts are still taken from `severity`
+ * so a future non-error conformance code cannot silently change the exit
+ * code.
+ *
+ * @public
+ */
+export declare const tally: (diagnostics: ReadonlyArray<RenderedDiagnostic>) => Tally;
+/**
+ * K-7/K-8's two lowest tiers: `2` when any conformance error is present, else
+ * `1` when any lint OR profile error is present, else `0`. Warnings and info
+ * never move it. `130`, `64` and `3` are set elsewhere — by the runtime's
+ * interrupt branch, by the `ShowHelp` remap in `bin.ts`, and by the typed
+ * errors' own `[Runtime.errorExitCode]` — so this function returns only
+ * `0 | 1 | 2`.
+ *
+ * @public
+ */
+export declare const forDiagnostics: (diagnostics: ReadonlyArray<RenderedDiagnostic>) => 0 | 1 | 2;
+//#endregion
+//#region src/render/human.d.ts
+/** The counts the summary line reports. @public */
+interface Counts {
+  readonly errors: number;
+  readonly warnings: number;
+  readonly info: number;
+  readonly concepts: number;
+}
+/**
+ * K-16. With a range:
+ * `<file>:<range.line + 1>:<range.character + 1> <severity> <code> <message>`.
+ * Without one: `<file> <severity> <code> <message>`. `file: ""` renders as
+ * the literal `(bundle)`. Core's range is zero-based (D-32,
+ * `CORE/Diagnostic.ts:49-57`); the `+ 1`s here are the only place it becomes
+ * one-based. Colour, when `color` is `true`, wraps ONLY the severity word
+ * (K-19) — never the code, the path, or the message.
+ *
+ * @public
+ */
+export declare const line: (diagnostic: RenderedDiagnostic, options?: {
+  readonly color?: boolean;
+}) => string;
+/**
+ * `sort` then `line` over the whole set: the exact stdout body of
+ * `--format human`, one array element per stdout line.
+ *
+ * @public
+ */
+export declare const human: (diagnostics: ReadonlyArray<RenderedDiagnostic>, options?: {
+  readonly color?: boolean;
+}) => ReadonlyArray<string>;
+/**
+ * K-20, verbatim and unpluralised —
+ * `<E> errors, <W> warnings, <I> info in <N> concepts (<root>)`. `root` is
+ * pre-rendered by the caller: relative to cwd when under it, absolute
+ * otherwise (K-51).
+ *
+ * @public
+ */
+export declare const summary: (counts: Counts, root: string) => string;
+//#endregion
+//#region src/render/json.d.ts
+/** One entry of the `diagnostics` array (K-21). @public */
+export declare const JsonDiagnostic: Schema.Struct<{
+  readonly source: Schema.Literals<readonly ["core.conformance", "core.lint", "profile"]>;
+  readonly file: Schema.String;
+  readonly code: Schema.String;
+  readonly severity: Schema.Literals<readonly ["error", "warning", "info"]>;
+  readonly message: Schema.String;
+  readonly range: Schema.optionalKey<typeof DiagnosticRange>;
+}>;
+/** @public */
+export type JsonDiagnostic = typeof JsonDiagnostic.Type;
+/** @public */
+export declare const JsonSummary: Schema.Struct<{
+  readonly conformance_errors: Schema.Number;
+  readonly lint_errors: Schema.Number;
+  readonly lint_warnings: Schema.Number;
+  readonly lint_info: Schema.Number;
+  readonly profile_errors: Schema.Number;
+  readonly concepts: Schema.Number;
+}>;
+/** @public */
+export type JsonSummary = typeof JsonSummary.Type;
+/**
+ * K-21's success envelope, snake_case. `exit_code` is `0 | 1 | 2` only: an
+ * infrastructure failure never produces this envelope, it produces the
+ * `JsonErrorEnvelope` (K-22).
+ *
+ * @public
+ */
+export declare const JsonEnvelope: Schema.Struct<{
+  readonly schema: Schema.Literal<1>;
+  readonly okfit_version: Schema.String;
+  readonly okf_version: Schema.String;
+  readonly root: Schema.String;
+  readonly profile: Schema.NullOr<Schema.String>;
+  readonly exit_code: Schema.Literals<readonly [0, 1, 2]>;
+  readonly summary: Schema.Struct<{
+    readonly conformance_errors: Schema.Number;
+    readonly lint_errors: Schema.Number;
+    readonly lint_warnings: Schema.Number;
+    readonly lint_info: Schema.Number;
+    readonly profile_errors: Schema.Number;
+    readonly concepts: Schema.Number;
+  }>;
+  readonly diagnostics: Schema.$Array<Schema.Struct<{
+    readonly source: Schema.Literals<readonly ["core.conformance", "core.lint", "profile"]>;
+    readonly file: Schema.String;
+    readonly code: Schema.String;
+    readonly severity: Schema.Literals<readonly ["error", "warning", "info"]>;
+    readonly message: Schema.String;
+    readonly range: Schema.optionalKey<typeof DiagnosticRange>;
+  }>>;
+}>;
+/** @public */
+export type JsonEnvelope = typeof JsonEnvelope.Type;
+/** K-22's envelope: the ONLY thing stdout carries under `--format json` on an exit-3 failure. @public */
+export declare const JsonErrorEnvelope: Schema.Struct<{
+  readonly schema: Schema.Literal<1>;
+  readonly okfit_version: Schema.String;
+  readonly exit_code: Schema.Literal<3>;
+  readonly error: Schema.Struct<{
+    readonly tag: Schema.String;
+    readonly message: Schema.String;
+  }>;
+}>;
+/** @public */
+export type JsonErrorEnvelope = typeof JsonErrorEnvelope.Type;
+/**
+ * Build the success envelope. `diagnostics` is sorted here with the same
+ * `sort` the human renderer uses (K-21's "diagnostics are in the K-17
+ * order"); `range` passes through as core computed it, zero-based.
+ *
+ * The value returned is in `Type` form (its `range`s are `DiagnosticRange`
+ * instances). What stdout carries is `Schema.encodeSync(JsonEnvelope)` of it,
+ * `JSON.stringify`-ed — one document, no trailing text.
+ *
+ * @public
+ */
+export declare const json: (input: {
+  readonly okfitVersion: string;
+  readonly okfVersion: string;
+  readonly root: string;
+  readonly profile: string | null;
+  readonly exitCode: 0 | 1 | 2;
+  readonly concepts: number;
+  readonly diagnostics: ReadonlyArray<RenderedDiagnostic>;
+}) => JsonEnvelope;
+/** K-22. `tag` is the error's `_tag` when it has one, else its constructor name. @public */
+export declare const jsonError: (error: unknown, okfitVersion: string) => JsonErrorEnvelope;
+//#endregion
+//#region src/render/verify.d.ts
+/**
+ * V-11's success envelope, schema 1, snake_case — the same convention as
+ * `render/json.ts`'s `JsonEnvelope`. Identical in shape for a dry run,
+ * which sets `dry_run: true` and still exits 0. There is no content tier,
+ * so `exit_code` is the literal `0`; a failure produces K-22's
+ * `JsonErrorEnvelope` instead, unchanged.
+ *
+ * @public
+ */
+export declare const VerifyEnvelope: Schema.Struct<{
+  readonly schema: Schema.Literal<1>;
+  readonly okfit_version: Schema.String;
+  readonly id: Schema.String;
+  readonly path: Schema.String;
+  readonly verified: Schema.Struct<{
+    readonly by: Schema.String;
+    readonly at: Schema.String;
+  }>;
+  readonly dry_run: Schema.Boolean;
+  readonly exit_code: Schema.Literal<0>;
+}>;
+/** @public */
+export type VerifyEnvelope = typeof VerifyEnvelope.Type;
+/**
+ * `path` is already the display form — `displayRoot(cwd, bundle.root, path)`
+ * joined to the bundle-relative `concept.path` — because `LoadedConcept.path`
+ * alone would print `decisions/cli-exit-codes.md`, not
+ * `okf/decisions/cli-exit-codes.md` (contract §12 note 5).
+ *
+ * @public
+ */
+export declare const verifyEnvelope: (input: {
+  readonly okfitVersion: string;
+  readonly id: string;
+  readonly path: string;
+  readonly by: string;
+  readonly at: string;
+  readonly dryRun: boolean;
+}) => VerifyEnvelope;
+/** @public */
+interface VerifyLines {
+  readonly id: string;
+  readonly by: string;
+  readonly at: string;
+  /** Every prior entry by the SAME actor, in list order (V-2). */
+  readonly priorAt: ReadonlyArray<string>;
+  readonly dryRun: boolean;
+  /** The exact bytes a real run would splice in; printed only when `dryRun`. */
+  readonly fragment: string;
+}
+/**
+ * V-11's human output: one line per fact. One `already verified` line per
+ * prior entry by the same actor, in list order (V-2 says "entries",
+ * plural), then the success line. A prior entry by a DIFFERENT actor is
+ * not called out: it stays on disk untouched (V-1) and is simply not this
+ * line's subject. Under `--dry-run` (I3), a `would write:` header and the
+ * exact fragment a real run would splice in follow, so the preview
+ * exercises — and shows — the same edit the write path would make.
  *
  * @public
  */
-declare const rootCommand: Command.Command<"okfit", {}, {}, never, never>;
+export declare const humanVerify: (input: VerifyLines) => ReadonlyArray<string>;
 //#endregion
-//#region src/index.d.ts
+//#region src/version.d.ts
 /**
- * The version string reported by `okfit --version`.
+ * The version string reported by `okfit --version`, read from the package's
+ * own manifest (K-32) so a release can never desync from the printed
+ * version. Consumed by `bin.ts` only.
  *
  * @public
  */
-declare const CLI_VERSION = "0.0.0";
+export declare const CLI_VERSION: string;
 //#endregion
-export { CLI_VERSION, rootCommand };
+export type { ConfigReadError, ContextResult, ContextRunOptions, Counts, DiagnosticSource, DiscoveredConfig, RenderedDiagnostic, ResolveProjectConfigInput, ResolvedProjectConfig, RunOptions, RunResult, ScaffoldFile, ScaffoldOptions, Tally, VerifyLines };
 //# sourceMappingURL=index.d.ts.map