okf-cli-0.4.0.0: CHANGELOG.md

# Changelog

All notable changes to okf are recorded here.

The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and
this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [Unreleased]

## [0.4.0.0] - 2026-07-30

### Added

- `okf profile show` prints `frontmatter.optional` at profile scope, under each
  type rule, and inside `elementFields`, using `(none)` when empty, so all three
  presence lists always print in the same order. Profile JSON emits the matching
  `optional` key in both rule records.
- `okf validate` renders the new `OptionalFieldWithCondition` profile-definition
  error, and the `ConflictingFieldRequirement` message now names all three
  presence lists. The profiles help topic gains an OPTIONAL FIELDS section and
  documents when to prefer `optional` over `recommended`.

### Changed

- Requires `okf-core ^>=0.4.0.0`. That release adds the `optional` field to
  `FrontmatterRules` and `NestedRules`, so a descriptor annotated against okf's
  current `Profile.dhall` by relative path must declare the third list.

## [0.3.0.0] - 2026-07-29

### Added

- `okf profile show` and profile JSON expose local-prefix, external-scheme, and
  self-reference policies. `okf validate` renders path-precise dangling,
  wrong-prefix, malformed, disallowed-external, and self-reference deviations;
  the profiles help topic documents the offline local/external boundary.
- `okf profile show` renders top-level and nested `when` predicates, while
  `okf validate` explains the activating condition on missing-field diagnostics.
  The profiles help topic documents same-scope resolution, compiler checks,
  strict recommendations, and no-cascade runtime behavior.
- `okf profile show` renders bounded nested field rules, and `okf validate`
  reports missing nested fields, non-record list elements, and nested value
  violations with indexed paths such as `reviews[2].outcome`.
- `okf profile show` and profile JSON expose named field formats, and
  `okf validate` renders parser-backed timestamp, date, URI, URI-scheme, and
  document-handle mismatches.
- Profile detail output and validation diagnostics for `Any`, `Scalar`, and
  `List` field cardinality.
- `okf profile show` now displays `allowUnknownFields` and each field's
  `allowedValues`; validation renders value-vocabulary and undeclared-field
  deviations.
- `okf profile show` and `--json` now expose required and recommended
  frontmatter rules beneath each type.
- `okf validate --strict --profile ...` checks profile-recommended fields and
  renders them as `missing profile-recommended field`; `--profile-enforce`
  continues to control whether the deviation fails the command.
- An `UPGRADING FROM 0.1.x` section in the `okf help profiles` topic, summarizing
  how to move a 0.1.x profile descriptor onto the 0.2.0.0 schema.
- Profile descriptions are surfaced everywhere a profile is displayed:
  `okf profile show` prints the profile's description, a `  - key: prose` line
  per frontmatter key, and a description line in each type block; `okf profile
  list` gains a trailing `DESCRIPTION` column reading `-` when absent; and
  `okf validate --profile` appends the key's prose in parentheses to a
  `missing profile-required field` advisory. A `DESCRIPTIONS` section in the
  `okf help profiles` topic covers all of it.

### Changed

- Requires `okf-core ^>=0.3.0.0`. This major bound reflects the breaking
  compiled-profile API and the expanded profile-rule and diagnostic types.
- Profile-definition output now reports invalid reference prefixes and schemes,
  undeclared target prefixes, missing `idField`, profile/type prefix conflicts,
  and reference-plus-format combinations. Mori and other exhaustive consumers
  must handle the five new reference violations and six definition errors, plus
  all previously accumulated profile API changes, before moving the matching
  `cabal.project` and `flake.nix` pins together.
- Profile-definition output now reports every invalid condition category. Mori
  and other exhaustive consumers must handle the new definition errors and the
  condition payload added to missing-field violations before updating their
  `okf-core` pin.
- Profile-definition output now reports invalid format parameters and
  contradictory profile/type formats. Mori and other exhaustive `okf-core`
  consumers must add cases for `InvalidFormatParameter`,
  `ConflictingFieldFormat`, and `ValueFormatMismatch` before updating their
  `okf-core` pin. Mori's renderer is
  `mori-cli/src/Mori/Okf/Advisory.hs`, and its matching `cabal.project` and
  `flake.nix` pins must move together.
- Profile descriptors are compiled before validation. Duplicate type names and
  ambiguous required/recommended declarations are fatal profile-definition
  errors reported once, before any concept is checked.
- Mori and other `okf-core` consumers must call `compileProfile`, handle its
  structured errors, pass `PermissiveConformance` or `StrictAuthoring` to
  `validateProfile`, and handle `MissingRecommendedProfileField` in exhaustive
  violation renderers.
- `okf profile show` prints a non-empty `frontmatter.required` or
  `frontmatter.recommended` as a headed block, one key per line, rather than one
  comma-joined line — per-key prose cannot share a line. An empty list keeps the
  single-line `(none)` form, so every optional field still prints.

## [0.2.0.0] - 2026-07-26

### Added

- `okf id next` and `okf id list` for allocating and listing profile-declared
  document handles, plus document-ID fallback in `okf show` so a handle such as
  `ADR-7` resolves to the concept that carries it.
- Optional `BUNDLE` and `CONCEPT_ID` arguments for `okf show`, filled in with `fzf`
  menus when omitted, plus the `okf help interactive` topic. Search roots default to
  the current directory and can be overridden with `OKF_BUNDLE_ROOTS`.

### Changed

- Requires `okf-core >=0.2.0.0`, whose profile Dhall schema gained the required
  `idField` and `idPrefix` record fields. Profile descriptors passed to
  `okf validate --profile` must add those values or adopt the new
  record-completion defaults.

## [0.1.2.1] - 2026-07-20

### Fixed

- Ship the `help/*.md` topic sources in the sdist via `extra-source-files`. They
  are embedded at compile time by `Okf.Cli.Help` (`file-embed`), so their absence
  from the 0.1.2.0 Hackage tarball made that release fail to build from Hackage.

## [0.1.2.0] - 2026-07-14

### Added

- `okf kit` command for installing reusable AI-agent skills and subagents from a
  configured `okf-kit` git repository (`list`, `install`, `update`, `uninstall`,
  `status`), with user and project (`--project`) scopes.
- `okf assist` command that launches an interactive Claude session seeded with a
  prompt and your installed okf skills on its path; `--print-command` prints the
  command line without launching.
- `okf config` command for managing the optional agent-assistance settings
  (`show`, `path`, `init`, `init --global`), sourced from `okf-config.dhall`,
  `~/.config/okf/config.dhall`, or `OKF_CONFIG` with built-in defaults.
- `okf help` topics for `kit`, `config`, and `agents` documenting the kit,
  configuration, and assist workflows.

### Changed

- Wired the baikai kit and agent-assist dependencies into the build.
- Updated the bundled baikai packages.

## [0.1.1.0] - 2026-06-28

### Added

- `okf --version`, including git SHA reporting for Cabal and Nix builds when
  available.
- Shell completion generation for supported shells.
- `okf help` command with embedded conceptual topic guides (`okf`, `format`,
  `validation`, `profiles`), including a guide explaining what the Open Knowledge
  Format is. The guides are plain text baked into the binary at compile time, so
  `okf help <topic>` works with no network or docs checkout.
- Profile-based validation: `okf validate --profile <descriptor>.dhall` checks a
  bundle against a team's house conventions (allowed `type` strings, required
  frontmatter keys, `resource:` schemes, file layout, and `# Schema` columns)
  declared in a Dhall descriptor. Profiles are not part of the OKF standard, so
  deviations are advisory by default; `--profile-enforce` fails the command on
  drift. Ships an example bundle (`examples/postgresql-sample`), a sample
  descriptor (`docs/profiles/postgresql.dhall`), and a user guide
  (`docs/user/profiles.md`).
- Log support: `okf-core` can parse, serialize, and validate `log.md` files;
  `okf-cli` can preview, validate, author log entries, and report drift between
  bundle logs and git history.
- Canonical OKF profile schema Dhall modules with drift tests.

### Changed

- Expanded the README and user guides to cover the current CLI, profile
  validation, and log workflows.
- Updated release, Nix, and repository metadata so both packages build and check
  as separate Hackage packages.

## [0.1.0.0] - 2026-06-19

Initial release.

### Added

- `okf-core` library: OKF document parser (`Okf.Document`), bundle graph
  indexing (`Okf.Index`, `Okf.Graph`), bundle validation with referential
  integrity (`Okf.Validation`, `Okf.Bundle`), concept construction and bundle
  writing, concept-link rendering with a round-trip guarantee, and a frontmatter
  authoring API.
- `okf-cli` library and `okf` executable: bundle validation and document
  authoring commands over the core API.