@okfit/cli 0.1.0 → 0.3.0

package/README.md

@@ -1,12 +1,341 @@
 # @okfit/cli
 
-The `okfit` command line for [Open Knowledge Format (OKF)](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md) bundles.
+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.
 
 > **Part of the okfit kit.** Most users want **[@okfit/plugin](https://www.npmjs.com/package/@okfit/plugin)**, which pulls this package in automatically.
 
-## Status
+## Usage
 
-Skeleton. `okfit --version` and `okfit --help` work; no subcommands yet.
+```text
+okfit [--help] [--version]
+okfit validate [path] [--config <file>] [--format human|json] [--skip-provenance] [--help]
+okfit init [path] [--profile <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]
+```
+
+`[path]` is the **project root** on every subcommand — the directory discovery
+starts from, and, for `init`, where `.config/okfit.toml` is written.
+It is never the bundle root; the bundle root is `<project root>/<bundle.path>`
+(`okf` by default). Default `[path]` is the current directory.
+
+### `okfit validate`
+
+Loads the config, loads the bundle, runs conformance and lint checks against
+it, runs the resolved profile's own checks, and renders every diagnostic.
+
+```console
+$ cd my-repo && okfit validate
+0 errors, 0 warnings, 0 info in 1 concepts (okf)
+$ echo $?
+0
+```
+
+A run that finds diagnostics prints one line per diagnostic to stdout, then
+the summary to stderr:
+
+```console
+$ okfit validate --config ./ci-config.toml
+warning: unknown profile "legacy-project"; continuing with defaults
+(bundle) warning config-unknown-key unknown top-level key "extra_section"
+modules/router.md:12:1 error required-key-missing missing required key "description"
+1 errors, 1 warnings, 0 info in 4 concepts (okf)
+$ echo $?
+1
+```
+
+Each diagnostic line is `<file>:<line>:<col> <severity> <code> <message>`
+(one-based line and column) when the diagnostic carries a range, or
+`<file> <severity> <code> <message>` when it does not; a bundle-level
+diagnostic (no file at all) prints `(bundle)` in place of `<file>`.
+Diagnostics sort by file (so `(bundle)` leads), then range-less before
+ranged, then by offset, then by code.
+
+`--skip-provenance` skips the `generated-at-drift` lint's git tier
+(`Provenance.lint`) for this one invocation, without touching the
+project's `[lint]` table — the same effect as `generated_at_drift = "off"`
+in config, scoped to a single run. The Claude Code plugin's PostToolUse
+hook passes it on every edit-time `validate` call so a git spawn per
+concept never runs on every keystroke-level edit; CI and the MCP
+`validate_bundle` tool omit the flag and keep the lint.
+
+### `okfit init`
+
+Scaffolds a fresh OKF bundle: a thin `.config/okfit.toml`, the
+bundle's root and per-directory `index.md` files, a `project.md` stub, and an
+initial `log.md` entry — then self-validates the result and exits with
+`validate`'s own exit code, so a scaffold that does not validate clean is a
+defect.
+
+```console
+$ mkdir my-repo && cd my-repo && okfit init
+Initialized okf with the software-project profile
+0 errors, 0 warnings, 0 info in 1 concepts (okf)
+$ echo $?
+0
+$ find . -type f | sort
+./.config/okfit.toml
+./okf/conventions/index.md
+./okf/decisions/index.md
+./okf/index.md
+./okf/interfaces/index.md
+./okf/log.md
+./okf/modules/index.md
+./okf/project.md
+./okf/references/index.md
+```
+
+`init` never overwrites. If any target path already exists, nothing is
+written:
+
+```console
+$ okfit init
+error: refusing to overwrite existing files:
+  .config/okfit.toml
+  okf/index.md
+  okf/log.md
+  okf/project.md
+  okf/modules/index.md
+  okf/decisions/index.md
+  okf/conventions/index.md
+  okf/interfaces/index.md
+  okf/references/index.md
+Nothing was written.
+$ echo $?
+3
+```
+
+`init` also refuses when any of the other two project-level names --
+`.okfit.toml` or `okfit.toml` -- already exists in the target directory,
+and names every colliding file in one error. An ancestor directory's config
+is a legitimate discovery hit, not a collision, and is never probed.
+
+`--profile <name>` picks the profile `init` scaffolds for (default: the
+config's `bundle.profile`, itself defaulting to `software-project`); an
+unrecognised name is a warning, not a failure — `init` continues with the
+default profile.
+
+### `okfit context`
+
+Prints the resolved project root, bundle root, config path, profile, and
+vocabulary (`types` and `tags` from the merged config) without loading the
+bundle. Useful for a script or a Claude Code hook that needs to know where
+the bundle lives before deciding whether to run `okfit validate`.
+
+```console
+$ okfit context
+project root: /abs/path/to/my-repo
+bundle root: /abs/path/to/my-repo/okf
+config: (none)
+profile: software-project
+index.md: /abs/path/to/my-repo/okf/index.md (exists)
+agent: (unset)
+
+types:
+  Convention  A rule contributors and agents must follow.
+  Decision  A choice made, the alternatives rejected, and why.
+  Interface  A contract others depend on.
+  Module  A unit of code with an owner and a boundary.
+  Project  The repository's root concept: its purpose, boundaries, and non-goals.
+  Reference  Mirrored external material kept under the references directory.
+
+tags:
+  architecture  Concerns the shape of the system rather than one module.
+  performance  Concerns speed, memory, or resource cost and the trade-offs made for them.
+  release  Concerns how changes ship: versioning, changelogs, publishing, and tagging.
+  security  Concerns trust boundaries, secrets, permissions, or attack surface.
+  testing  Concerns how the system is verified: strategy, fixtures, and coverage policy.
+```
+
+All paths `humanContext` prints are absolute, exactly as the resolved envelope carries them
+(never relativized to the current directory the way `validate`'s summary line is) — the
+example above reflects that, not a shortened path for readability.
+
+`--format json` uses its own envelope, `ContextEnvelope` (schema 1),
+documented in `## --format json` below — never `validate`'s `JsonEnvelope`.
+There is no `--profile` flag on `context`; that one belongs to `init`
+alone. Config discovery, the `--config` pre-flight, and the K-4/K-15
+warnings all behave exactly as `## Config discovery` describes below.
+
+### `okfit verify`
+
+Appends one attestation, `{ by: human:<id>, at: <now> }`, to a concept's
+`verified` list and writes the file back. `<id>` is a concept id with or
+without a leading slash or trailing `.md`. The actor is always your own git
+identity, resolved from `user.name`/`user.email` and `[actors].humans`;
+there is no `--by`. Existing entries are never touched or replaced — every
+run appends, including a repeat by the same person. `--at <iso>` records a
+different instant; `--dry-run` runs the same splice and prints the exact
+fragment it would write, under a `would write:` line, without touching the
+file. Exit `0` on success (a dry run included), `3` on any failure.
+
+A read-only concept is overwritten anyway — the write goes through a temp
+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.
+
+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.
+
+## Config discovery
+
+With no `--config` flag, `okfit` walks upward from `[path]` (default:
+the current directory). In each directory it checks `<dir>/.okfit.toml`,
+then `<dir>/okfit.toml`, then `<dir>/.config/okfit.toml` before moving
+up one level, so a child directory's `okfit.toml` always beats a
+parent's `.okfit.toml`. Past the project it falls back to
+`$XDG_CONFIG_HOME/okfit/config.toml` (and `$XDG_CONFIG_DIRS`), then the
+OS-native config directory
+(`~/Library/Application Support/okfit/config.toml` on macOS,
+`%APPDATA%\okfit\config.toml` on Windows), then `/etc/okfit/config.toml`
+on Linux and macOS. First match wins; nothing merges across levels, and
+`okfit` never probes for a `.git` directory.
+
+The project root anchors on the matched file's own directory -- except
+for `.config/okfit.toml`, which anchors on the parent of `.config`. An
+XDG, native, system-tier or absent config anchors on the current
+directory instead.
+
+Because the upward walk never stops at `$HOME`, it reaches `$HOME` itself
+before falling through to the XDG tier. `~/.config/okfit.toml` and
+`~/okfit.toml` are therefore **project-tier** files, not the personal
+defaults they look like: the walk finds them like any other project
+config, wins over the XDG tier, and anchors the project root at `$HOME`
+-- so every project under `$HOME` with no config of its own resolves
+against a stray `~/.config/okfit.toml`. Personal defaults belong at
+`$XDG_CONFIG_HOME/okfit/config.toml` (note the extra `okfit` directory),
+not directly under `~/.config/`.
+
+`--config <file>` bypasses discovery entirely — no upward walk, no XDG probe
+— and anchors the project root the same way. An explicit path inside a
+`.config` directory anchors on that directory's parent, exactly as a
+discovered one does. A path that does not exist is a hard failure:
+
+```console
+$ okfit validate --config ./missing.toml
+error: config path not found: /abs/missing.toml
+$ echo $?
+3
+```
+
+A config whose `okf_version` disagrees with the version this `okfit` speaks
+is a warning, not a failure; the run continues.
+
+## Exit codes
+
+| Code | Meaning |
+| --- | --- |
+| `130` | Interrupted (Ctrl-C) |
+| `64` | Usage error: an unknown flag or subcommand |
+| `3` | Infrastructure failure: bad `--config` path, malformed or unreadable config, unset `HOME`, unreadable bundle root, or `init`'s overwrite refusal |
+| `2` | One or more conformance diagnostics of severity error |
+| `1` | One or more lint or profile diagnostics of severity error |
+| `0` | Otherwise |
+
+Higher wins when several apply. Warnings and info never change the exit
+code.
+
+`okfit context` never produces `1` or `2`: it prints orientation data and
+never runs conformance or lint checks.
+
+## `--format json`
+
+`okfit validate --format json` prints exactly one JSON document to stdout and
+nothing else (no summary line, no warnings — those still go to stderr):
+
+```json
+{
+ "schema": 1,
+ "okfit_version": "0.1.0",
+ "okf_version": "0.2",
+ "root": "/abs/path/to/my-repo/okf",
+ "profile": "software-project",
+ "exit_code": 1,
+ "summary": {
+  "conformance_errors": 0,
+  "lint_errors": 1,
+  "lint_warnings": 1,
+  "lint_info": 0,
+  "profile_errors": 0,
+  "concepts": 4
+ },
+ "diagnostics": [
+  {
+   "source": "core.lint",
+   "file": "",
+   "code": "config-unknown-key",
+   "severity": "warning",
+   "message": "unknown top-level key \"extra_section\""
+  },
+  {
+   "source": "core.lint",
+   "file": "modules/router.md",
+   "code": "required-key-missing",
+   "severity": "error",
+   "message": "missing required key \"description\"",
+   "range": { "offset": 87, "length": 9, "line": 11, "character": 0 }
+  }
+ ]
+}
+```
+
+`profile` is `null` when the config sets `bundle.profile = "none"` or names a
+profile `okfit` does not recognise. `range` is zero-based, exactly as
+`@okfit/core` computed it, and omitted for a range-less diagnostic.
+
+An infrastructure failure under `--format json` prints a different, smaller
+envelope to stdout and exits `3`:
+
+```json
+{ "schema": 1, "okfit_version": "0.1.0", "exit_code": 3, "error": { "tag": "ConfigPathNotFoundError", "message": "config path not found: /abs/ci-config.toml" } }
+```
+
+`init` has no `--format`; it is human output only.
+
+`okfit context --format json` prints its own envelope, distinct from the
+one above:
+
+```json
+{
+ "schema": 1,
+ "project_root": "/abs/path/to/my-repo",
+ "bundle_root": "/abs/path/to/my-repo/okf",
+ "config_path": null,
+ "profile": "software-project",
+ "profile_requested": null,
+ "index_path": "/abs/path/to/my-repo/okf/index.md",
+ "index_exists": true,
+ "actors": { "agent": null },
+ "types": [
+  { "name": "Project", "description": "The repository's root concept: its purpose, boundaries, and non-goals.", "guidance": "..." }
+ ],
+ "tags": [
+  { "name": "architecture", "description": "Concerns the shape of the system rather than one module." }
+ ]
+}
+```
+
+Every field is present, even when unset (`config_path`, `profile`,
+`profile_requested`, and `actors.agent` are `null`, never an omitted key) --
+unlike `JsonDiagnostic`'s `range`, this envelope has no optional keys at all.
+
+`profile_requested` is the profile name the config asked for after the
+default rule, 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 the config sets
+`bundle.profile = "none"`). The two differ only when a config names a
+profile `okfit` does not recognise — `profile` is `null` but
+`profile_requested` still names what was asked for, so `okfit context
+--format human` prints `profile: (none) (requested <name>, unknown)` in
+that one case.
+
+## Message conventions
+
+Every message `okfit` prints is lowercase, starts `error:` or `warning:`,
+never ends with a trailing period, and renders a path relative to the
+current directory when the path is under it, absolute otherwise. Colour, when
+stdout is a TTY and `NO_COLOR` is not `1`, wraps only the severity word —
+never the code, the path, or the message text.
 
 ## License
 

package/bin/okfit.js

@@ -1,10 +1,5 @@
 #!/usr/bin/env node
-import { rootCommand } from "../commands/root.js";
-import { CLI_VERSION } from "../index.js";
-import { Effect } from "effect";
-import { Command } from "effect/unstable/cli";
-import * as NodeRuntime from "@effect/platform-node/NodeRuntime";
-import * as NodeServices from "@effect/platform-node/NodeServices";
+import { main } from "../main.js";
 
 //#region src/bin.ts
 /**
@@ -12,8 +7,7 @@ import * as NodeServices from "@effect/platform-node/NodeServices";
 *
 * @packageDocumentation
 */
-const cli = Command.run(rootCommand, { version: CLI_VERSION });
-NodeRuntime.runMain(cli.pipe(Effect.provide(NodeServices.layer)));
+main();
 
 //#endregion
 export {  };

package/commands/context.js

@@ -0,0 +1,75 @@
+import { setExitCode } from "../internal/exit.js";
+import { humanContext } from "../render/context.js";
+import { CLI_VERSION } from "../version.js";
+import { Argument, Command, Flag } from "effect/unstable/cli";
+import { ContextEnvelope, contextEnvelope, jsonError, provideConfig, resolveProjectConfig, runContext } from "@okfit/engine";
+import { Console, Effect, Option, Schema } from "effect";
+
+//#region src/commands/context.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"));
+/** No `--profile` flag: M-15's exact ruling; that flag belongs to `init` alone. */
+const formatFlag = Flag.choice("format", ["human", "json"]).pipe(Flag.withDefault("human"), Flag.withDescription("output format: human (default) or json"));
+/**
+* `okfit context [path] [--config <file>] [--format human|json]`.
+*
+* Handler order fixed by the contract (§8.3): steps 1–7 are
+* `validateCommand`'s handler in substance (both now share
+* `@okfit/engine`'s `resolveProjectConfig` — A4) — 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) — then it diverges: `runContext` (index.md stat only,
+* never `Bundle.load`), build the envelope, render, and always exit `0`
+* (there is no content tier: `context` never runs conformance or lint
+* checks, so C-3.5's `1`/`2` codes have no analogue here).
+*
+* @public
+*/
+const contextCommand = Command.make("context", {
+	path: pathArg,
+	config: configFlag,
+	format: formatFlag
+}, (input) => Effect.gen(function* () {
+	const cwd = process.cwd();
+	const discoveryCwd = Option.getOrElse(input.path, () => cwd);
+	const body = Effect.gen(function* () {
+		const { projectRoot, bundleRoot, config: merged, profile, profileName, discovered } = yield* resolveProjectConfig({
+			pathArg: input.path,
+			explicitConfigPath: input.config,
+			cwd
+		});
+		const { indexPath, indexExists } = yield* runContext({ bundleRoot });
+		const configPath = Option.match(discovered, {
+			onNone: () => Option.isSome(input.config) ? input.config.value : null,
+			onSome: (source) => source.path
+		});
+		const profileRequested = configPath === null ? null : profileName;
+		const envelope = contextEnvelope({
+			projectRoot,
+			bundleRoot,
+			configPath,
+			profile: Option.match(profile, {
+				onNone: () => null,
+				onSome: (p) => p.name
+			}),
+			profileRequested,
+			indexPath,
+			indexExists,
+			config: merged
+		});
+		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
+	}));
+	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("Print the resolved project root, bundle root, config path, profile, and type/tag vocabulary without loading the bundle."));
+
+//#endregion
+export { contextCommand };

package/commands/init.js

@@ -0,0 +1,171 @@
+import { setExitCode } from "../internal/exit.js";
+import { useColor } from "../internal/tty.js";
+import { displayRoot, human, summary } from "../render/human.js";
+import { Argument, Command, Flag } from "effect/unstable/cli";
+import { CONFIG_RELATIVE_PATH, InitOverwriteError, Now, SCHEMA_DIRECTIVE, collect, configValue, files, forDiagnostics, provideConfig, resolveBundleRoot, resolveProjectRoot, run, targetPaths } from "@okfit/engine";
+import { Console, DateTime, Effect, FileSystem, Layer, Option, Path, Schema } from "effect";
+import { TomlCodec } from "@effected/config-file";
+import { Git } from "@effected/git";
+import { OKF_SPEC_VERSION, OkfitConfig, OkfitConfigFile } from "@okfit/core";
+import { GitHistory, Profiles } from "@okfit/profiles";
+
+//#region src/commands/init.ts
+/**
+* `[path]` is the PROJECT root (K-2), never the bundle root — identical to
+* `validate`'s own argument (`Argument.path` resolves it absolute at the
+* parse boundary, satisfying 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` — existence is checked by `provideConfig`, identical to `validate`'s flag. */
+const configFlag = Flag.file("config").pipe(Flag.optional, Flag.withDescription("explicit config file; skips discovery"));
+/**
+* K-3: `Flag.string`, deliberately not `Flag.choice` against
+* `PROFILE_NAMES` (`PROFILES/Profile.ts:10`) — an unrecognised name is a
+* 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)"));
+/**
+* Stands in for `profile.config` when `Profiles.get` returns `None`.
+* `OkfitConfig.merge` only visits `Object.keys(override)`
+* (`CORE/OkfitConfig.ts:229-245`), so merging this in leaves every other key
+* at the base's value — it exists only to satisfy `merge`'s signature.
+*/
+const NO_PROFILE_CONFIG = { extensions: {} };
+/**
+* `bundle` and `bundle.profile`/`bundle.path` are all `optionalKey` in the
+* schema (`CORE/OkfitConfig.ts`), so the type checker sees `string |
+* undefined` two levels deep even though `OkfitConfig.DEFAULTS` always sets
+* both at runtime — the same `??` fallback `commands/validate.ts`'s own
+* `DEFAULT_PROFILE_NAME` uses.
+*/
+const DEFAULT_PROFILE_NAME = OkfitConfig.DEFAULTS.bundle?.profile ?? "software-project";
+/** See {@link DEFAULT_PROFILE_NAME}. */
+const DEFAULT_BUNDLE_PATH = OkfitConfig.DEFAULTS.bundle?.path ?? "okf";
+const countsOf = (diagnostics, concepts) => ({
+	errors: diagnostics.filter((diagnostic) => diagnostic.severity === "error").length,
+	warnings: diagnostics.filter((diagnostic) => diagnostic.severity === "warning").length,
+	info: diagnostics.filter((diagnostic) => diagnostic.severity === "info").length,
+	concepts
+});
+/**
+* `okfit init [path] [--profile <name>] [--config <file>]` (K-2, K-3; no
+* `--format`, human output only, K-6).
+*
+* Handler order, fixed by the contract:
+*
+*  1. `cwd = process.cwd()`; `discoveryCwd = Option.getOrElse(path, () => cwd)`.
+*  2. `provideConfig({ explicitConfigPath: config, discoveryCwd })` wraps
+*     everything from step 3 on, identical to `validate`'s own pre-flight
+*     (K-57).
+*  3. `sources = yield* (yield* OkfitConfigFile).discover`; the winner is
+*     `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)`.
+*     `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
+*     no profile resolved.
+*  6. `merged.okf_version !== OKF_SPEC_VERSION` warns (K-15).
+*  7. `projectRoot`/`bundleRoot` via `@okfit/engine`'s `config/anchor.ts`; `now = yield* Now`;
+*     `layout` falls back to `Profiles.softwareProject.layout` when no
+*     profile resolved (this file's own decision 2 above — `Layout` has no
+*     `DEFAULTS` equivalent).
+*  8. `paths = targetPaths(...)`; every path stat-ed; ANY existing fails
+*     with `InitOverwriteError` before a single byte is written (K-28).
+*  9. `mkdir -p` every target's parent, THEN write `configValue(...)`
+*     through `OkfitConfigFile.write` and every `files(...)` entry through
+*     `fs.writeFileString` — `OkfitConfigFile.write` deliberately does not
+*     create its parent (`CF/index.d.ts:517-521`), and `save` is unusable
+*     here since it targets the XDG `defaultPath`, which K-14 forbids.
+* 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
+*     `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();
+	const discoveryCwd = Option.getOrElse(input.path, () => cwd);
+	yield* provideConfig({
+		explicitConfigPath: input.config,
+		discoveryCwd
+	})(Effect.gen(function* () {
+		const winner = (yield* (yield* OkfitConfigFile).discover)[0];
+		const fileConfig = winner === void 0 ? { extensions: {} } : winner.value;
+		const profileName = Option.getOrElse(input.profile, () => fileConfig.bundle?.profile ?? DEFAULT_PROFILE_NAME);
+		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);
+		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;
+		const projectRoot = resolveProjectRoot({
+			pathArg: input.path,
+			explicitConfigPath: input.config,
+			discovered: winner === void 0 ? Option.none() : Option.some({
+				path: winner.path,
+				resolver: winner.resolver
+			}),
+			cwd,
+			path
+		});
+		const bundleRoot = resolveBundleRoot(projectRoot, merged, path);
+		const now = yield* Now;
+		const scaffoldOptions = {
+			projectRoot,
+			bundleRoot,
+			layout: Option.match(profile, {
+				onNone: () => Profiles.softwareProject.layout,
+				onSome: (resolved) => resolved.layout
+			}),
+			profileName,
+			projectTitle: path.basename(projectRoot),
+			today: DateTime.formatIso(now).slice(0, 10)
+		};
+		const paths = targetPaths(scaffoldOptions);
+		const existing = [];
+		for (const target of paths) if (yield* fs.exists(target)) existing.push(target);
+		if (existing.length > 0) return yield* new InitOverwriteError({
+			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 encoded = yield* Schema.encodeEffect(OkfitConfig)(configValue({
+			...scaffoldOptions,
+			bundlePath
+		}));
+		const toml = yield* TomlCodec.stringify(encoded);
+		yield* fs.writeFileString(`${projectRoot}/${CONFIG_RELATIVE_PATH}`, `${SCHEMA_DIRECTIVE}${toml}`);
+		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`);
+		const result = yield* run({
+			root: bundleRoot,
+			config: merged,
+			profile,
+			now
+		}).pipe(Effect.provide(Layer.mergeAll(Git.layer, GitHistory.layer)));
+		const diagnostics = collect(result.report.conformance, result.report.lint, result.profileDiagnostics);
+		for (const line of human(diagnostics, { color: useColor() })) yield* Console.log(line);
+		yield* Console.error(summary(countsOf(diagnostics, result.bundle.concepts.size), displayRoot(cwd, bundleRoot, path)));
+		setExitCode(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."));
+
+//#endregion
+export { initCommand };

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 };