okf-cli-0.5.0.0: help/log.md

LOG FILES AND STALENESS

A log.md is a reserved Markdown file recording dated changes for its directory
scope. It has a title, YYYY-MM-DD date headings, and bullet entries:

  # tables Update Log

  ## 2026-06-23
  * **Update**: Refreshed schema

COMMANDS

  okf log BUNDLE                    Print every discovered log.md.
  okf log BUNDLE --check-stale      Report concepts newer than their log.
  okf log BUNDLE --since REF        Ask git which changes skipped their log.
  okf log add BUNDLE [CONCEPT_ID] --kind Update -m "Refreshed schema"

  okf log BUNDLE prints each log preceded by its bundle-relative path:

    --- tables/log.md
    # tables Update Log

    ## 2026-06-23
    * **Update**: Refreshed schema

TWO STALENESS CHECKS

  --check-stale reports concepts whose generated date is newer than the newest
  entry in the nearest enclosing log.md -- the content changed and the log did
  not say so.

  --since REF uses git to report concept .md files changed since REF when their
  nearest enclosing log.md was not changed in the same diff. If git is
  unavailable, or the bundle is not in a git checkout, the git drift check is
  skipped with a message rather than failing.

  Both are advisory. okf validate runs the same date check as part of
  validation, where --log-enforce makes those advisories fail the command:

    okf validate BUNDLE --log-enforce

  This log staleness is not the stale_after deadline okf trust reports. This one
  compares dates between a concept and its log; that one reads a deadline the
  concept declares about itself.

APPENDING AN ENTRY

  okf log add BUNDLE CONCEPT_ID --kind Update -m "Refreshed schema"
  okf log add BUNDLE --kind Update -m "Reorganized the bundle"
  okf log add BUNDLE CONCEPT_ID --kind Update -m "..." --date 2026-06-23

  With a CONCEPT_ID the entry goes in that concept's directory log.md, creating
  the file if absent. Without one it goes in the root log.md. --kind is the
  leading bold label and defaults to Update; -m/--message is required; --date
  writes a specific YYYY-MM-DD heading instead of today's in UTC.

  Re-running the same command adds another bullet; it does not deduplicate.

VALIDATION

  A present log.md must use valid YYYY-MM-DD calendar headings and non-empty
  date groups. okf validate treats a malformed log.md as a hard error in both
  permissive and strict modes -- unlike staleness, which is only ever advisory.

  A bundle generated by okf profile document with --timestamp or --generated-at
  has dates but no log.md, so do not check generated documentation with
  --log-enforce.

SEE ALSO

  okf help index        The other reserved file.
  okf help validation   Log advisories inside okf validate.
  okf help trust        stale_after deadlines, a different check.