okf-cli-0.5.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.5.0.0] - 2026-08-01

### Added

- `okf trust BUNDLE` reports every concept's derived trust tier, `status`, and
  staleness as one aligned row per concept. A tier is computed from `verified`
  on each run and never read from the bundle.
- `okf sources BUNDLE` lists the OKF v0.2 provenance each concept records, with
  the credibility signals `author`, `usage_count`, and `last_modified`, and the
  effective usage window per entry. Concepts with no `sources` are skipped, and
  entries are never sorted or ranked by `usage_count`.
- `okf index BUNDLE --write --okf-version MAJOR.MINOR` declares an OKF version
  in the bundle root `index.md`. Without the flag, an existing declaration is
  preserved and an absent one stays absent — previously, regenerating indexes
  silently destroyed a declaration.
- `okf show` prints the v0.2 families a concept carries — `generated`, the
  derived `trust` tier, the latest `verified` date, `status`, `stale_after` with
  its staleness verdict, and a `sources` count.
- `okf validate` renders the new core diagnostics, including the join between a
  body's footnote labels and its `sources` ids in both directions.
- `okf validate --profile` reports deviations inside an object-valued
  frontmatter key, at paths such as `generated.by`, and refuses a descriptor that
  pairs `objectFields` with an explicit scalar or list cardinality:
  `objectFields at generated cannot be combined with cardinality scalar`.
  `okf profile document` renders the new rule kind as an `- Object fields:`
  bullet, which changes generated output for every profile; the committed
  `examples/postgresql-profile/` bundle is regenerated accordingly.
- `okf computations BUNDLE` lists every attested computation a bundle declares,
  one aligned row each, in the house style of `okf trust` and `okf sources`: the
  concept ID, the `runtime`, the `parameters`, where the computation lives, and
  which of §10.2's two run-and-check halves the concept declares. Selection is on
  the `type` frontmatter value being exactly `Attested Computation`. Every column
  restates frontmatter and none says anything about a run — a receipt and a
  verdict live outside the bundle and okf never executes or attests anything. An
  absent value prints as `(no runtime)`, `(no computation)`, `(2 computations)`,
  or `(neither)` rather than as a blank cell, so the report hides nothing that
  `okf validate --strict` reports. A bundle with no computations prints nothing
  and exits 0.
- `okf show CONCEPT --computation` prints a concept's computation and nothing
  else, in whichever of §10.3's two forms its producer chose — reading the file
  named by `computation` rather than printing its path. Offering none, or more
  than one, exits non-zero rather than guessing.
- `okf show` renders the §10.2 contract in the specification's own field order,
  printing each line only when the concept declares it.
- `examples/ddd-ordering` ships a worked attested computation at
  `computations/order-total.md`, with a `references/skills/` executor and a
  `references/attesters/` attester, and a test asserting it validates strictly.
- `okf profile document --generated-by ACTOR` sets the actor recorded in
  `generated.by` on every generated page. Accepts any OKF v0.2 actor shape:
  `<producer>/<version>`, `human:<id>`, or `process:<id>`.
- `okf profile document --generated-at RFC3339` records a timestamp in
  `generated.at`. Omitted entirely when not given, because generation never
  reads the clock.
- `okf profile document --okf-version MAJOR.MINOR` declares the OKF version in
  the generated bundle's root index, spelled and validated exactly as the flag
  of the same name on `okf index`. Omitting it preserves any declaration the
  destination already carries rather than deleting one.
- `okf validate --profile` reports a bundle whose `okf_version` declaration does
  not meet the profile's `requireBundleVersion`, as `bundle does not declare
  okf_version; this profile requires 0.2 or later` or `bundle declares
  okf_version 0.1; …`. Advisory like every other profile deviation and fatal
  under `--profile-enforce`. It is the one violation that names no concept.
- `okf profile show` prints a `requireBundleVersion:` line, and `--json` gains
  the matching key.

### Changed

- **`okf profile show` renders `objectFields`.** It printed `elementFields` and
  not its counterpart, so a profile constraining the members of a mapping-valued
  key displayed that rule nowhere. The gap was not hypothetical: the shipped
  `docs/profiles/okf-v0-2.dhall` constrains the members of `generated`,
  `verified`, and `usage_window`, and none of it was visible. The two nested
  shapes now print together, `objectFields` first, matching
  `okf profile document`, which already rendered its object-fields bullet in that
  position. Every field rule gains at least an `objectFields: (none)` line, so
  the output of this command changes for every profile.
- **The embedded `okf help` topics describe OKF v0.2.** `okf help format` listed
  `timestamp` among current frontmatter fields and `# Citations` as a
  conventional body heading, and named no v0.2 family at all; `okf help
  validation` required `timestamp` under `--strict` and opened its conformance
  section with "OKF v0.1 conformance"; and `okf help okf` asserted the tool
  tracks the v0.1 specification while listing five of fourteen commands. All
  three are current. `format` gains the six v0.2 families, an ATTESTED
  COMPUTATIONS section, the `references/` convention, and the §6.2 path grammar;
  `validation` gains the strict-mode diagnostics, a VERSION DECLARATION section,
  and one statement of why every optional-family check is strict-only.
- `okf validate --strict` reports a path in a frontmatter value that names a file
  the bundle does not hold, which no check saw before. Only `resource` and the
  three attested-computation path fields; `sources[].resource` is deliberately
  exempt because §5.1 sanctions a scope descriptor there.
- `okf index` lists a directory's non-Markdown files, so a `references/attesters/`
  directory holding only `.py` files no longer generates a one-byte `index.md`.
- `okf validate --profile` resolves a `path` rule against every file in the
  bundle rather than only `.md` concepts.
- A missing member of a nested record now carries the member's `description`
  prose in parentheses — `missing profile-required field: generated.by (Who or
  what produced this content.)` — as a missing top-level key already did. This
  applies to list-element members too, and adds nothing where a member declares
  no description.
- **`okf validate` names a declared OKF version in its success line**:
  `OK: 4 concepts (okf_version 0.2)`. The suffix appears only when the bundle's
  root `index.md` declares a version, so a bundle that declares nothing prints
  exactly `OK: N concepts` as before.
- **Strict validation asks for `generated` rather than `timestamp`.** It falls
  back to a legacy `timestamp`, so nothing that passed before fails now, but the
  message for a concept with neither changes to
  `missing generated field (or legacy timestamp)`. In a bundle that declares
  `okf_version: "0.2"`, a concept still carrying `timestamp` is additionally
  reported under `--strict`; an undeclared bundle never is.
- **`okf log --check-stale` and `okf validate --log-enforce` read `generated.at`
  first**, falling back to `timestamp`, and the advisory says `generated date`
  rather than `timestamp date`.
- The shipped `docs/profiles/postgresql.dhall` now requires its bundles to
  declare `okf_version` at 0.2 or later, since its own rules are written for
  v0.2 and `examples/postgresql-sample` already declares it. The shipped
  `docs/profiles/okf-v0-2.dhall` deliberately does not: §12 makes the
  declaration a MAY, and a format-level reference profile that demanded one
  would advise the opposite of the specification.
- `okf profile document` now writes `generated.by: process:okf-profile-document`
  on every page by default, so default output passes `okf validate --strict`
  without `--timestamp`. The default actor is deliberately version-free: a
  version-bearing one would change every generated byte on every okf release and
  break the drift check that committed documentation exists to provide.
- `--timestamp` still writes the superseded OKF v0.1 `timestamp` key and is
  unchanged, but is now needed only when producing a v0.1 bundle.
- Requires `okf-core ^>=0.5.0.0` with the OKF v0.2 core semantics, the attested
  computation contract, the path-valued frontmatter rules, and the
  profile-declared bundle version requirement.

### Fixed

- `okf-cli-test` passes from the released sdist. Nine tests assert against
  artifacts committed to the okf repository — `docs/profiles/`, `examples/`, and
  `okf-core`'s fixtures — none of which cabal will package into `okf-cli`'s
  tarball, because they sit outside the package tree. They previously aborted the
  whole suite on the first missing file, so `cabal test` failed for anyone
  building from Hackage, nixpkgs included. Each now reports `SKIP` when the
  repository tree is absent and runs unchanged inside it.

## [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.