{
"markdown": "\n\n```\n ██████╗ ██╗ ██╗███████╗██╗\n██╔═══██╗██║ ██╔╝██╔════╝██║\n██║ ██║█████╔╝ █████╗ ██║\n██║ ██║██╔═██╗ ██╔══╝ ██║\n╚██████╔╝██║ ██╗██║ ██║\n ╚═════╝ ╚═╝ ╚═╝╚═╝ ╚═╝\n```\n\n# OKFI — Open Knowledge Format Interface\n\n**A terminal browser, editor, and PDF exporter for [Open Knowledge Format](https://github.com/GoogleCloudPlatform/knowledge-catalog) (OKF) bundles.**\n\nRoam project → project through your OKF catalogs in a fast, keyboard-driven,\nBBS-flavored TUI — read them, fold them, edit them, and typeset them.\n\n\n\n\n\n\n\n\n
\n\n---\n\n## Contents\n\n- [What is this?](#what-is-this)\n- [Screenshot](#screenshot)\n- [Install](#install)\n- [Quick start](#quick-start)\n- [Usage](#usage)\n - [Command-line flags](#command-line-flags)\n - [Key bindings](#key-bindings)\n- [Configuration](#configuration)\n- [Features](#features)\n- [How discovery works](#how-discovery-works)\n- [PDF export](#pdf-export)\n- [The OKF catalog](#the-okf-catalog)\n- [Development](#development)\n- [Roadmap](#roadmap)\n- [License](#license)\n\n---\n\n## What is this?\n\n[OKF](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md) is a\nvendor-neutral, agent-agnostic standard for project knowledge: plain Markdown files with\nYAML frontmatter, no database, no SDK. A **bundle** is a directory of *concept* files (one\nper `.md`), plus the reserved `index.md` and `log.md`.\n\n**okfi** is a single-file C/ncurses program that browses those bundles:\n\n- discovers every bundle under your configured search roots and lists them in a **picker**;\n- shows each bundle as a **type-grouped, collapsible tree** with counts;\n- renders concept bodies with real **Markdown styling** (headings, emphasis, code, tables,\n links) and follows in-bundle **cross-links**;\n- lets you **edit** concepts in place (built-in editor or `$EDITOR`) and **scaffold** new\n bundles/concepts;\n- **exports** a concept to a typeset PDF.\n\n> [!NOTE]\n> The OKF spec is deliberately silent on *where* bundles live. okfi assumes the practical\n> model: **decentralized storage** (one `okf/` per project repo, so the catalog travels with\n> its code) + **centralized browsing** (one tool that roams across all of them). See\n> [How discovery works](#how-discovery-works).\n\n## Screenshot\n\n```text\n┌ TREE ──────────────────┬ CONTENT ───────────────────────────────────────────┐\n│ ▾ Reference (3) │ # Schema │\n│ OKF format │ │\n│ Orders table │ | Column | Type | Description | │\n│ ▸ Playbook (1) │ |-------------|--------|--------------------------| │\n│ ▾ ADR (2) │ | order_id | STRING | Globally unique order id │ │\n│ Storage choice │ | customer_id | STRING | FK to customers │ │\n│ > Component (1) │ │\n│ ▾ reserved (2) │ See [customers](/tables/customers.md). │\n│ index.md │ │\n│ log.md │ │\n└────────────────────────┴─────────────────────────────────────────────────────┘\n content line 1/14 [1]customers\n```\n\n*(The focused pane is outlined and its title highlighted; on a color terminal the `bbs`\ntheme renders it in vivid cyan/magenta on blue.)*\n\n## Install\n\n> [!IMPORTANT]\n> **Requirements:** a C11 compiler (`cc`/`gcc`), `ncursesw` (wide-character ncurses, found\n> via `pkg-config`), and a POSIX system. PDF export additionally needs `pdflatex` and the\n> [`milstd`](#pdf-export) LaTeX kit — neither is needed to build or browse.\n\n```sh\ngit clone https://github.com/theesfeld/okfi.git\ncd okfi\nmake\n```\n\nThis produces the `okfi` binary in the project directory.\n\n\nWhat make runs
\n\n```sh\ncc -std=c11 -Wall -Wextra -O2 $(pkg-config --cflags ncursesw) \\\n -o okfi okfi.c $(pkg-config --libs ncursesw)\n```\n\nThe build is warning-free under `-Wall -Wextra`. Run the built-in self-check with\n`./okfi --selftest` (exits `0` on success).\n \n\n## Quick start\n\n```sh\n./okfi # browse every bundle under your search roots\n./okfi path/to/okf # open one bundle directly (skips the picker)\n./okfi --new-bundle ./okf # scaffold a fresh OKF bundle here\n```\n\nOn first run with no config, okfi seeds sensible search roots (the parent of your current\ndirectory, and `~/Projects` if it exists) and writes them to its config file.\n\n## Usage\n\n### Command-line flags\n\n| Flag | Effect |\n|------|--------|\n| *(none)* | Browse all bundles discovered under the search roots |\n| `` | Open that bundle directly |\n| `--root DIR` | Add a search root for this run (repeatable) |\n| `--mono`, `--no-color` | Force the monochrome interface |\n| `--new-bundle DIR` | Scaffold a bundle (`index.md` + `log.md`) |\n| `--new-concept BUNDLE NAME [TYPE]` | Scaffold a concept (default type `Concept`) |\n| `--export-pdf CONCEPT.md` | Export a concept to `./.pdf` |\n| `--selftest` | Run the built-in self-check |\n| `--help`, `-h` | Usage |\n\n### Key bindings\n\n**Bundle picker**\n\n| Key | Action |\n|-----|--------|\n| `j` / `k`, `↓` / `↑` | move |\n| `Enter` | open the selected bundle |\n| `N` | create a new bundle |\n| `,` | settings · `?` help · `q` quit |\n\n**Browser**\n\n| Key | Action |\n|-----|--------|\n| `F9` / `\\` | open the menu bar (File · Edit · View · Settings · Help) |\n| `j` / `k`, `↑` / `↓` | move within the focused pane |\n| `l` / `→`, `h` / `←` | focus the content pane / the tree |\n| `Tab` | collapse/expand the current group |\n| `Shift+Tab` / `*` | collapse all groups / expand all |\n| `Space` / `Enter` | fold a group, or open a concept |\n| `g` / `G`, `J` / `K`, `PgDn`/`PgUp` | first/last · scroll the body |\n| `1`–`9` | follow a numbered cross-link |\n| `e` / `n` / `E` | edit · new concept · export PDF |\n| `Esc` | back to the bundle list |\n| `,` / `?` / `q` | settings / help / quit |\n\n**Editor** (built-in)\n\n| Key | Action |\n|-----|--------|\n| arrows, `Home` / `End` | move (by codepoint) |\n| `^O` | save (atomic) |\n| `^X` / `Esc` | cancel (single-key discard prompt) |\n\n## Configuration\n\nConfig lives in an XDG-compliant location — `$XDG_CONFIG_HOME/okfi/config` (falling back to\n`~/.config/okfi/config`). It is plain text, hand-editable, **written on every in-program\nchange**, and **preserves unknown keys** on rewrite.\n\n```ini\n# search roots — repeatable\nroot = /home/me/Projects\nroot = /home/me/work\n\ntheme = bbs # dark | light | bbs | mono\neditor = internal # internal (built-in) | system ($VISUAL/$EDITOR)\ngroup_order = count # type | count | priority\ngroup_priority = ADR,Reference # for group_order = priority\n\n# per-role color overrides (256-colour indices, or `default`)\ncolor.head = 51\ncolor.bar = 231,21 # fg,bg\n\n# fold state (written automatically when you collapse a group)\nfold = /home/me/Projects/foo/okf\treserved\n```\n\n> [!TIP]\n> Everything is configurable from the in-app **settings screen** (`,`) — theme, editor,\n> group order (the `priority` list is prompted for), search roots, and every colour role.\n> Collapse state **persists across runs**, keyed per bundle.\n\n\nColor roles you can override
\n\n`head` · `bold` · `ital` · `code` · `link` · `codeblk` · `key` · `bar` · `tag`\n\nEach takes `fg` or `fg,bg` as 0–255 terminal colour indices (or `default` for the terminal\ndefault). A set override beats the active theme.\n \n\n## Features\n\n- **Multi-bundle discovery** over configurable search roots, with a project→project picker.\n- **Type-grouped tree** — headers per `type` with counts (`▾ Reference (3)`), collapsible\n (`Space`, or `*` for all), three orderings (`type` / `count` / `priority`), and fold state\n persisted per bundle.\n- **Markdown rendering** — ATX headings, `**bold**`, `*italic*`, `` `code` `` (CommonMark\n backtick-run spans, **nested** emphasis), `[links]` with in-bundle cross-link following,\n bullet/blockquote, **pipe tables** (aligned, honoring `:--`/`--:`/`:--:`), fenced code,\n word-wrap with soft-line-break reflow, UTF-8 throughout.\n- **Editor** — a built-in, codepoint-aware editor with **atomic** (temp + `rename`) saves,\n or your `$EDITOR`, selectable in settings.\n- **Scaffolding** — new bundles and concepts (in-app or via CLI) that emit spec-conformant\n skeletons and prepend dated `log.md` entries.\n- **Color** — automatic 256/16-colour detection, `bbs`/`default`/`mono` themes, per-role\n overrides; honours `NO_COLOR`.\n- **PDF export** — see below.\n- **Self-check** — `--selftest` exercises the frontmatter parser, inline styler, tables,\n cross-links, and LaTeX escaping.\n\n## How discovery works\n\n```mermaid\nflowchart LR\n A[\"search roots
(config)\"] --> B{scan tree
depth ≤ 5}\n B -->|\"index.md has okf_version\"| C[\"bundle root\"]\n B -->|\"dir named okf with .md\"| C\n C --> D[\"picker
(project → project)\"]\n D -->|Enter| E[\"browser
(one bundle)\"]\n E -->|e| F[\"editor / $EDITOR\"]\n E -->|\"--export-pdf\"| G[\"milmanual PDF\"]\n```\n\nA directory is treated as a **bundle root** when its `index.md` carries `okf_version` (the\nspec's canonical marker) or it is an `okf/`-named directory containing concept `.md` files.\nSymlinks are skipped and the scan is depth-bounded, so it is safe to point a root at a large\ntree.\n\n## PDF export\n\n`okfi --export-pdf ` emits a LaTeX document and runs `pdflatex`, writing\n`./.pdf`.\n\n> [!WARNING]\n> PDF export uses the **`milstd`** military-document LaTeX kit (US technical-manual style),\n> expected at `~/.config/milstd/`, plus a working `pdflatex`. The frontmatter becomes a\n> `booktabs` table, headings map to `\\section`/numbered paragraphs, pipe tables to\n> `booktabs` tabulars, and fenced code to `listings`. All concept text is LaTeX-escaped; the\n> engine is launched without a shell.\n\n## The OKF catalog\n\nThis repository dogfoods OKF: its own knowledge catalog lives in [`okf/`](okf/).\n\n| Concept | What it documents |\n|---------|-------------------|\n| [`okf-format.md`](okf/okf-format.md) | the OKF subset okfi parses |\n| [`discovery.md`](okf/discovery.md) | bundle discovery + the placement model |\n| [`tui-viewer.md`](okf/tui-viewer.md) | the browser view, tree, styling, cross-links |\n| [`editor.md`](okf/editor.md) | the in-TUI editor |\n| [`create.md`](okf/create.md) | scaffolding bundles and concepts |\n| [`config.md`](okf/config.md) | every config option and the settings screen |\n| [`pdf-export.md`](okf/pdf-export.md) | the PDF pipeline |\n| [`build.md`](okf/build.md) | building and running |\n\n## Development\n\n```sh\nmake # build (warning-free under -Wall -Wextra)\n./okfi --selftest # run the assert-based self-check\nmake clean\n```\n\nThe program is a single translation unit, [`okfi.c`](okfi.c). Standard C11 for the language;\nncursesw and POSIX (`fork`/`exec`, `mkdtemp`, `open_memstream`, …) for the runtime.\n\n## Roadmap\n\n- [x] Multi-bundle discovery + picker\n- [x] Collapsible type tree with counts, persisted folds, configurable order\n- [x] Markdown rendering (nested inline, tables, cross-links, reflow)\n- [x] In-TUI editor (atomic save) and `$EDITOR` option\n- [x] PDF export (milstd `milmanual`)\n- [ ] Horizontal scroll for very wide tables\n- [ ] Interactive link navigation beyond digit jumps\n- [ ] Whole-bundle PDF (one document, chapter per concept)\n\n## License\n\n> [!NOTE]\n> No license file is present yet — until one is added, all rights are reserved by the\n> author. If you'd like to use or contribute, open an issue.\n\n---\n\n\nBuilt with C, ncursesw, and a fondness for old bulletin boards.\n
\n",
"bytes": 12155,
"sha": "ab60985ab0eae6765e0bfea58676a7dc9a2649497166c64b9b9c5a6550b76c2e",
"repo_slug": "theesfeld/okfi",
"fonte": "repo",
"truncated": false,
"api": "https://agentalog.com/api/listings/okf_theesfeld_okfi_okf_index_md_3691df0d/readme"
}