okf 1.4.0 → 1.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (43) hide show
  1. checksums.yaml +4 -4
  2. data/CHANGELOG.md +50 -0
  3. data/README.md +15 -15
  4. data/lib/okf/bundle/search.rb +155 -0
  5. data/lib/okf/bundle.rb +2 -2
  6. data/lib/okf/cli.rb +68 -4
  7. data/lib/okf/server/app.rb +29 -0
  8. data/lib/okf/server/graph/template.html.erb +256 -40
  9. data/lib/okf/skill/SKILL.md +17 -11
  10. data/lib/okf/skill/playbooks/consume.md +4 -2
  11. data/lib/okf/skill/playbooks/maintain.md +6 -4
  12. data/lib/okf/skill/playbooks/menu.md +10 -6
  13. data/lib/okf/skill/playbooks/search.md +42 -0
  14. data/lib/okf/skill/reference/authoring.md +2 -2
  15. data/lib/okf/skill/reference/cli.md +55 -17
  16. data/lib/okf/version.rb +1 -1
  17. data/lib/okf.rb +1 -0
  18. metadata +3 -26
  19. data/.okf/capabilities/agent-skill.md +0 -46
  20. data/.okf/capabilities/graph-server.md +0 -63
  21. data/.okf/capabilities/index.md +0 -20
  22. data/.okf/capabilities/library-api.md +0 -72
  23. data/.okf/capabilities/linter.md +0 -49
  24. data/.okf/capabilities/read-views.md +0 -84
  25. data/.okf/capabilities/validator.md +0 -40
  26. data/.okf/cli.md +0 -52
  27. data/.okf/design/core-shell-split.md +0 -58
  28. data/.okf/design/index.md +0 -10
  29. data/.okf/design/ruby-floor.md +0 -45
  30. data/.okf/design/runtime-dependencies.md +0 -44
  31. data/.okf/design/server-trust-boundary.md +0 -40
  32. data/.okf/format/citations.md +0 -33
  33. data/.okf/format/cross-links.md +0 -52
  34. data/.okf/format/frontmatter.md +0 -38
  35. data/.okf/format/index.md +0 -9
  36. data/.okf/format/okf-format.md +0 -43
  37. data/.okf/index.md +0 -18
  38. data/.okf/log.md +0 -10
  39. data/.okf/model/bundle.md +0 -38
  40. data/.okf/model/concept.md +0 -44
  41. data/.okf/model/graph.md +0 -44
  42. data/.okf/model/index.md +0 -8
  43. data/.okf/overview.md +0 -67
data/.okf/overview.md DELETED
@@ -1,67 +0,0 @@
1
- ---
2
- type: Overview
3
- title: okf-gem at a glance
4
- description: A light Ruby gem that reads, validates, lints, and serves Open Knowledge Format v0.1 bundles.
5
- tags: [okf, gem, overview, diagram]
6
- timestamp: 2026-07-12T12:00:00Z
7
- ---
8
-
9
- # Overview
10
-
11
- **okf-gem** — `okf` on RubyGems — operates on [OKF v0.1](format/okf-format.md)
12
- bundles: directories of Markdown files with YAML frontmatter that humans and
13
- agents both read from one source. It does not define new knowledge storage; it
14
- gives you leverage over knowledge that already lives as Markdown.
15
-
16
- ```mermaid
17
- flowchart LR
18
- skill["companion<br/>agent skill"] -. authors/curate .-> bundle[("OKF v0.1 bundle<br/>Markdown + YAML")]
19
- bundle --> model["pure model<br/>Concept · Bundle · Graph"]
20
- skill -. execute .-> cli
21
- subgraph cli ["okf CLI"]
22
- validate["validate — legal? §9"]
23
- lint["lint — well-curated?"]
24
- server["server — explore"]
25
- end
26
- model --> cli
27
- model --> library["library API<br/>embed in Ruby"]
28
- ```
29
-
30
- Over such a bundle the gem gives you five capabilities behind one
31
- [command-line tool](cli.md):
32
-
33
- | Capability | What it answers | Verb |
34
- | -------------------------------------------------------- | --------------------------------- | ---------------- |
35
- | [Companion agent skill](capabilities/agent-skill.md) | Can an agent author it? | `skill` |
36
- | [Conformance validator](capabilities/validator.md) | Is this a legal OKF bundle? (§9) | `validate` |
37
- | [Curation linter](capabilities/linter.md) | Is it navigable, complete, fresh? | `lint` / `loose` |
38
- | [Interactive graph server](capabilities/graph-server.md) | Can I explore it visually? | `server` |
39
- | [Library API](capabilities/library-api.md) | Can my Ruby program use it? | (in-process) |
40
-
41
- Alongside those, a family of [read views](capabilities/read-views.md) —
42
- `index`, `catalog`, `files`, `tags`, `stats`, `graph` — print the bundle at a
43
- glance so an agent reads it without a browser.
44
-
45
- # The two ideas it inherits from the format
46
-
47
- - **Dual audience.** Every file serves a human skimming it _and_ an agent
48
- extracting from it, so bodies are structural Markdown and
49
- [links](format/cross-links.md) are plain Markdown links — both readers already
50
- understand them.
51
- - **The graph is emergent.** Files are nodes, Markdown links are edges. You never
52
- declare a graph; the gem [builds one](model/graph.md) from how concepts link.
53
-
54
- # Design ethos
55
-
56
- The gem is deliberately light so it runs on the Ruby an OS already ships. That
57
- ethos is not incidental — it is enforced by [hard constraints](design/):
58
- a [Ruby 2.4 floor](design/ruby-floor.md), exactly
59
- [two runtime dependencies](design/runtime-dependencies.md), and a
60
- [core/shell split](design/core-shell-split.md) that keeps all logic pure and
61
- testable without disk. Everything else — no ActiveSupport, no build step, no
62
- JavaScript toolchain — follows from those.
63
-
64
- # Citations
65
-
66
- [1] [README.md](https://github.com/serradura/okf-gem/blob/main/README.md) — the gem's own overview.
67
- [2] [AGENTS.md](https://github.com/serradura/okf-gem/blob/main/AGENTS.md) — the maintainer guide.