okf 1.6.0 → 1.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 45d6619cf9144fbaf4026e51ad238213e916c6796ffd1199d189d6b64c47352e
-  data.tar.gz: c26b86f1b2173feefd02159a2dd280f93a4e8ee915eb077ef49558fced6c8ac3
+  metadata.gz: 64b163bdb5b0e234c879f6d5424279b8b329a797292b6322af0379741e06565c
+  data.tar.gz: 816d6456345e3cd6e507be229b757f8143987ba2c98ffb1bcc26d45c19bdfba2
 SHA512:
-  metadata.gz: 254038bdb6383fe94882793c6b2d2433917536793670d23fad1be4c2678e9a8c042164c997ba8ae64950ced447ca850e4263bb1eee9ab2230b33b2b83f8efd94
-  data.tar.gz: 1ada5ef52a4848d340619a1ccf10bc35ddbae7504c3e53cc447f824e44f90d145579a024ae17c15c38eb84cc0592353b20967adda709c631a38a298161e6f99f
+  metadata.gz: 9ee06f232154bf609ce24882447de92f26e8a33ebddd593ff462bb83ad993d4f79c797a0c88f7647cbea9bba05b190a0b1da127e01e53d99a9b5e99d952eb76b
+  data.tar.gz: 69a26c944a1a393f7bcb58cdfd554ed1991c0617fe3fe9d7e138af7dd9847763df947d393a9cea1ff99182430b5f79b488bde78a79f0915740beab088501c4bd

data/CHANGELOG.md

@@ -1,5 +1,31 @@
 # Changelog
 
+## [1.7.0] - 2026-07-16
+
+- `okf server`: responses are gzipped when the client accepts it
+  (`Rack::Deflater` at the boot seam). Lossless and transparent — the browser
+  decompresses automatically — and no new dependency, since `Rack::Deflater`
+  ships inside rack. Clients that send no `Accept-Encoding` keep getting
+  identity responses. `okf render`'s static HTML is untouched.
+- The agent skill gains a `migrate` verb (`playbooks/migrate.md`): convert
+  existing documentation into a conformant bundle **in place** — frontmatter
+  and reserved files added, bodies kept verbatim (`produce` keeps
+  distillation). The verb is routed from SKILL.md's Commands table and intent
+  inference, the menu playbook now leads with it when a target already holds
+  markdown docs, and pointing any verb at a directory that is not a bundle now
+  suggests `migrate` instead of grinding through the validate errors.
+- The graph page's link-preview image points at the renamed
+  `okfgem.com/og-demo-v3.png`. The site's OG art was refreshed to drop "Live
+  Graph" from the package formula (it is `Agent Skill + CLI/Lib + Graph` now
+  that `okf render` makes the graph live *or* static), and the filename carries
+  the version so social scrapers pick the new art up.
+- The plugin's `/okf:gem` command is now a pass-through shim: it hands its
+  arguments to the okf skill unchanged, making `SKILL.md` the single router
+  for every channel. The routing prose the command used to duplicate had no
+  drift guard (the sync test covers only the generated skill copy), and the
+  not-a-bundle `migrate` suggestion now lives in `SKILL.md`, so standalone
+  skill installs get it too.
+
 ## [1.6.0] - 2026-07-15
 
 - New CLI verb: `okf render <dir> [-o FILE]` — the live graph as one static,

data/README.md

@@ -73,6 +73,44 @@ It is deliberately light so it runs on the Ruby your OS already ships:
 That range is not aspirational: CI runs the full test suite and RuboCop on every
 one of these on each push.
 
+## Try it in four steps
+
+From zero to your first bundle.
+
+**1. Get the `okf` command.** Two ways in; either one puts `okf` on your `PATH`.
+
+```bash
+gem install okf                                        # with Ruby
+curl -fsSL https://docker.okfgem.com/install.sh | sh   # no Ruby? Docker
+```
+
+**2. Install the skill.** Teach your agent the format — Claude Code, or any
+other agent.
+
+```bash
+okf skill .claude   # or: okf skill .agents
+```
+
+**3. Start an agent session** where your project lives.
+
+```bash
+claude
+```
+
+**4. Make your first bundle.** Two ways in, by what you already have: docs keep
+every word, code gets written up for you.
+
+```
+/okf migrate <path-to-your-docs>            # have docs? adopted in place, bodies verbatim
+/okf produce based on <path-to-your-code>   # only code? the skill authors the concepts
+```
+
+> [!TIP]
+> **Once you have a bundle**, run `/okf maintain` in the agent session to keep it
+> in sync as the code changes, and `okf server <folder>` to explore it as a graph.
+> In Claude Code, the [plugin](#claude-code-plugin) adds a post-edit curation hook
+> that runs `validate` + `lint` for you.
+
 ## Why OKF
 
 Project knowledge (why a service exists, what a metric really measures, the
@@ -297,6 +335,7 @@ The skill routes a small set of verbs. In Claude Code they run as `/okf:gem
 | _(none)_         | Orient on the bundle and recommend the highest-value next move                                              |
 | `search`         | Answer a question from the bundle, token-lean: the map, the finder, only the winning bodies                 |
 | `produce`        | Create or extend a bundle from code, docs, or knowledge in people's heads                                   |
+| `migrate`        | Adopt existing Markdown docs in place: frontmatter and reserved files added, bodies kept verbatim           |
 | `maintain`       | Sync the bundle's content with reality after the code or docs change                                        |
 | `consume`        | Use the bundle as context for a task, writing back what you learn                                           |
 | `curate`         | Structural upkeep as it stands: `validate` + `lint` + `loose`                                               |
@@ -455,7 +494,7 @@ The plugin carries three pieces:
 | Piece         | What it does                                                                                                                                                                                                                                                                                                                                                                                                             |
 | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
 | `okf` skill   | The [companion skill](#agent-skill) above, bundled with the plugin (a generated copy that `rake plugin:sync` keeps identical to `lib/okf/skill`).                                                                                                                                                                                                                                                                        |
-| `/okf:gem`    | The front door, routed by argument. No arguments: orients on the CLI, the bundle, and what `validate`/`lint` report, then recommends the highest-value next move (never auto-runs). `doctor`: installs and verifies the `okf` CLI, then doctors the repo's bundle. `curate`: the full curation cycle (`validate` + `lint` + `loose`). Anything else (`produce`, `maintain`, `consume`, a CLI verb): handed to the skill. |
+| `/okf:gem`    | The front door: a pass-through that hands its arguments to the skill unchanged, so the [verb table](#agent-skill) above is the whole routing story — `doctor` installs and verifies the CLI, `curate` runs the full cycle (`validate` + `lint` + `loose`), `produce`/`migrate`/`maintain`/`consume` and any CLI verb do what they say. No arguments: orients on the CLI, the bundle, and what `validate`/`lint` report, then recommends the highest-value next move (never auto-runs). |
 | Curation hook | After every Write or Edit inside a bundle, runs `okf validate` + `okf lint` and returns the findings as context. The checks are the CLI's own, so the feedback is deterministic.                                                                                                                                                                                                                                         |
 
 The hook stays silent outside bundles, and when the CLI is missing it suggests

data/lib/okf/cli.rb

@@ -194,6 +194,7 @@ module OKF
 
     def server(argv)
       require "okf/server/app"
+      require "rack/deflater"
 
       options = { port: 8808, bind: "127.0.0.1", title: nil, link: nil, layout: "cose" }
       parser = OptionParser.new do |o|
@@ -216,6 +217,7 @@ module OKF
     # tests drive this without a socket).
     def run_server(folder, options)
       app = OKF::Server::App.new(folder, title: options[:title] || folder.name, link: options[:link], layout: options[:layout])
+      app = Rack::Deflater.new(app) # gzip responses when the client accepts it — transparent, no new dependency
       @out.puts "serving #{folder.graph.nodes.size} concepts at http://#{options[:bind]}:#{options[:port]} (Ctrl-C to stop)"
       @runner.call(app, options[:bind], options[:port])
     end

data/lib/okf/server/graph/template.html.erb

@@ -8,7 +8,7 @@
 <meta property="og:site_name" content="OKF">
 <meta property="og:title" content="<%= og_title %>">
 <meta property="og:description" content="<%= og_desc %>">
-<meta property="og:image" content="https://okfgem.com/og-demo-v2.png">
+<meta property="og:image" content="https://okfgem.com/og-demo-v3.png">
 <meta property="og:image:type" content="image/png">
 <meta property="og:image:width" content="1200">
 <meta property="og:image:height" content="630">
@@ -16,7 +16,7 @@
 <meta name="twitter:card" content="summary_large_image">
 <meta name="twitter:title" content="<%= og_title %>">
 <meta name="twitter:description" content="<%= og_desc %>">
-<meta name="twitter:image" content="https://okfgem.com/og-demo-v2.png">
+<meta name="twitter:image" content="https://okfgem.com/og-demo-v3.png">
 <meta name="twitter:image:alt" content="An interactive Open Knowledge Format knowledge graph.">
 <link rel="icon" href="data:image/svg+xml,<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 100 100'><rect width='100' height='100' rx='24' fill='%231a1a1a'/><polygon points='38,44 62,44 50,82' fill='%237a0a1e'/><polygon points='18,44 38,44 50,82' fill='%23a8112c'/><polygon points='62,44 82,44 50,82' fill='%23a8112c'/><polygon points='35,28 18,44 38,44' fill='%23dc1e3c'/><polygon points='65,28 82,44 62,44' fill='%23dc1e3c'/><polygon points='35,28 65,28 62,44 38,44' fill='%23f43f5e'/><polygon points='36,29 49,29 42,42' fill='%23fff' opacity='.38'/><polygon points='35,28 65,28 82,44 50,82 18,44' fill='none' stroke='%23ff6b7f' stroke-width='2' stroke-linejoin='round'/></svg>">
 <script>/* Resolve theme before first paint so there is no flash. */

data/lib/okf/skill/SKILL.md

@@ -116,7 +116,8 @@ read the modelling craft in [authoring.md](reference/authoring.md) before
 producing or maintaining, and the verbatim spec [SPEC.md](reference/SPEC.md)
 when you need chapter and verse.
 
-**No subcommand?** Infer intent: "document this / capture X" → `produce`; "the
+**No subcommand?** Infer intent: "document this / capture X" → `produce`;
+"convert / migrate / OKFy these existing docs into a bundle" → `migrate`; "the
 code changed, update the docs" → `maintain`; "what do we know about X / where
 is X documented" → `search`; a repo already carrying a bundle plus a task
 needing its knowledge → `consume`; "check / graph / preview it" → run the
@@ -126,6 +127,11 @@ matching CLI verb and interpret the result. When genuinely ambiguous, ask.
 root, but first detect whether the project already keeps its bundle elsewhere
 (e.g. `docs/`) and prefer that. Commit the bundle alongside the code it describes.
 
+**Target isn't a bundle?** When a verb points at a directory that holds markdown
+but no root `index.md` carrying `okf_version` — `validate` failing wholesale on
+missing frontmatter — don't grind through the errors: suggest `migrate` (OKFy it
+in place, bodies verbatim) and let the user pick.
+
 ## Commands
 
 The first word of the arguments picks a row. **No arguments at all** — someone
@@ -139,6 +145,7 @@ Read the referenced playbook before executing — it *is* the procedure.
 | *(none)*   | Orient | recommend the highest-value next move; never auto-run | [playbooks/menu.md](playbooks/menu.md) |
 | `search`   | Use    | answer a question from the bundle: map → finder → only the winning bodies | [playbooks/search.md](playbooks/search.md) |
 | `produce`  | Author | create or extend a bundle | [playbooks/produce.md](playbooks/produce.md) |
+| `migrate`  | Author | convert existing docs in place: frontmatter + reserved files, bodies verbatim | [playbooks/migrate.md](playbooks/migrate.md) |
 | `maintain` | Author | sync the bundle's content with reality after a change | [playbooks/maintain.md](playbooks/maintain.md) |
 | `consume`  | Use    | use the bundle as context for a task | [playbooks/consume.md](playbooks/consume.md) |
 | `curate`   | Curate | structural upkeep as it stands: validate + lint + loose | [playbooks/curate.md](playbooks/curate.md) |

data/lib/okf/skill/playbooks/menu.md

@@ -11,8 +11,11 @@ is the lede.
    here. Everything below needs the CLI.
 2. **Bundle present?** Locate one: the directory you were given, else a `.okf/`
    directory or a root `index.md` whose frontmatter carries `okf_version`.
-   - **No bundle** → lead with **`produce`** (create the first bundle from the
-     code, docs, or what lives only in people's heads). Nothing else applies yet.
+   - **No bundle** → when the target (or an obvious docs directory) already
+     holds markdown documentation, lead with **`migrate`** (OKFy it in place —
+     frontmatter on, bodies verbatim); otherwise lead with **`produce`**
+     (create the first bundle from the code, docs, or what lives only in
+     people's heads). Nothing else applies yet.
 3. **Read the bundle's state** from the CLI, not by eyeballing:
    `okf validate <root>`, `okf lint <root>`, `okf loose <root>` — the plain
    text views, which are lighter than `--json` when you are reading a report

data/lib/okf/skill/playbooks/migrate.md

@@ -0,0 +1,42 @@
+# Playbook: migrate — OKFy existing docs in place
+
+Adopt documentation that already *is* the knowledge: frontmatter on, reserved
+files in, every body kept **verbatim**. The output must be recognizably the
+input — when the documents should instead be distilled into new concepts, that
+is [produce.md](produce.md), not migrate. If the `okf` CLI is missing, stop and
+follow [doctor.md](doctor.md) first.
+
+Bodies are sacred: migrate never rewrites, reorders, or summarizes a body — the
+one permitted edit besides prepending frontmatter is repointing a relative link
+that a file move broke. <!-- rule:okf-migrate-verbatim -->
+Read the modelling craft in [authoring.md](../reference/authoring.md) before a
+non-trivial migration; its type and tag rules apply here unchanged.
+
+1. **Inventory from the validator, not by eyeballing.** `okf validate <dir>
+   --json` enumerates every file missing frontmatter or `type` and every
+   malformed reserved file — that list is the worklist, and the pass is done
+   when it reports zero.
+2. **Prepend frontmatter; do not touch the body below it.** Use the frontmatter
+   block of [templates/concept.md](../templates/concept.md): a small `type`
+   vocabulary derived from what the documents *are* (reuse before minting —
+   check `okf types <dir>` as you go), `title`/`description` from each
+   document's own heading and purpose line, `timestamp` from the document's own
+   date when it carries one, `tags` only where connective.
+3. **Keep the directory topology** — it is already domain knowledge. Default
+   one file = one concept. When a file shows split signals (two `type`s
+   fighting for the frontmatter, two audiences), flag it for a later `curate`
+   pass; never split, rename, or restructure during migration.
+4. **Reserved files.** A bundle-root `index.md` from
+   [templates/root-index.md](../templates/root-index.md) (frontmatter is
+   `okf_version: "0.1"` and nothing else), a nested `index.md` per directory
+   from [templates/index.md](../templates/index.md), and `log.md` with a dated
+   **Creation** entry naming where the documents came from.
+5. **Links.** The documents' existing relative links become the graph's edges —
+   verify they resolve inside the bundle and repoint only what a move broke.
+   Links pointing outside the bundle are tolerated (§5.3); leave them.
+6. **Close out** — walk the
+   [Closeout gate](../reference/authoring.md#closeout--the-finishing-gate):
+   `validate` zero errors, `lint` (pass `--stale-after` when you stamped
+   timestamps), `loose`, tag review, index eyeball. Then prove the promise:
+   each concept with its frontmatter block stripped is byte-identical to the
+   source document.

data/lib/okf/skill/playbooks/produce.md

@@ -8,7 +8,8 @@ vocabulary, topology, links, citations — lives in
 2. Pick the source(s): **code** (derive concepts from source, READMEs, docstrings,
    config), **docs/wiki** (distill pages into concepts; cite the originals under
    `# Citations`), **manual** (decisions, playbooks, metrics that live only in
-   people's heads).
+   people's heads). If the source documents should survive as the concepts
+   themselves — verbatim — that is [migrate.md](migrate.md), not produce.
 3. Choose a domain-based directory layout. One concept per file.
 4. Write each concept from [templates/concept.md](../templates/concept.md): a
    descriptive `type` from the bundle's vocabulary, recommended fields filled,

data/lib/okf/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module OKF
-  VERSION = "1.6.0"
+  VERSION = "1.7.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: okf
 version: !ruby/object:Gem::Version
-  version: 1.6.0
+  version: 1.7.0
 platform: ruby
 authors:
 - Rodrigo Serradura
@@ -87,6 +87,7 @@ files:
 - lib/okf/skill/playbooks/doctor.md
 - lib/okf/skill/playbooks/maintain.md
 - lib/okf/skill/playbooks/menu.md
+- lib/okf/skill/playbooks/migrate.md
 - lib/okf/skill/playbooks/produce.md
 - lib/okf/skill/playbooks/search.md
 - lib/okf/skill/reference/APACHE-2.0.txt