okf 1.2.0 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 95f1db166e67b4a3c4b4fbd679bce25ef19e3de3f50f010e13e6b1630ddacfcf
-  data.tar.gz: cef59494dbd959585ba85f631b025eb5ba88ab94e38c6d440ac8aed1b2fbd61a
+  metadata.gz: 3ba14268a02a3bc64e391bd522723c79b1dd9b8c146f341bb57b74397abbd0ea
+  data.tar.gz: 85b2f13ab45e83bb894cd681c36b0cbf4db161484b9c7de28fd186572e4c633e
 SHA512:
-  metadata.gz: ff17b4c61c5e9fb63e63235fb19fb51b75ce7626acafdfaa88a367f5a6c40a2e9c2eabe7af0283fac5cf6edfd1349b22aa900fa23c321522bd29b19e76befd95
-  data.tar.gz: 8846d3604a36b3818024f21d88d04cc62bc91d374dac1a7fd34e17d6eb8269fcf72f7675191a1b3243144359d847c734cf049d4025cf962fb5bf7369f7cc8fac
+  metadata.gz: 9f549361de5213dc0ef48506ffc62e3e668631a38c4666f82e005fd6f6be4f9e5e667e6daa995c0db86785d6f17d9f2c557d97e04ee75e7c1b9d8ad3cab69f47
+  data.tar.gz: 2c39cd025790fea098fab4e30a9ebcaf3bc48dc797b4336253f967142f47edab339985b034769259380e366d10882d15fef611a8796bb057d43f87b96fc0b7ff

data/.okf/design/server-trust-boundary.md

@@ -2,7 +2,7 @@
 type: Constraint
 title: The server trust boundary
 description: The served page sanitizes each concept body before rendering and escapes inlined data, so both XSS paths into the page are closed.
-resource: lib/okf/server/templates/graph.html.erb
+resource: lib/okf/server/graph/template.html.erb
 tags: [security, server, xss]
 timestamp: 2026-07-12T12:00:00Z
 ---
@@ -17,9 +17,9 @@ carry active content. Two defenses handle that — one for each path into the pa
 
 There are two data paths into the page, and each carries its own guard:
 
-| Path | Handling | Safe? |
-|------|----------|-------|
-| Graph data **inlined** into the page | through `json_for_script`, which escapes `<` | yes — it cannot break out of its `<script>` |
+| Path                                               | Handling                                                                                     | Safe?                                                        |
+| -------------------------------------------------- | -------------------------------------------------------------------------------------------- | ------------------------------------------------------------ |
+| Graph data **inlined** into the page               | through `json_for_script`, which escapes `<`                                                 | yes — it cannot break out of its `<script>`                  |
 | Concept bodies **fetched** on demand (`/node?id=`) | `marked` renders the Markdown, then `DOMPurify.sanitize` scrubs it before it reaches the DOM | yes — scripts, handlers, and `javascript:` URLs are stripped |
 
 The [description](../format/cross-links.md) shown in the inspector takes a third
@@ -31,10 +31,10 @@ path and never needs the client's help: the server escapes it
 DOMPurify removes the code, not the content. The page still fetches and shows the
 links, images, and Mermaid diagrams a body names (Mermaid runs in its `strict`
 mode), and it pulls Cytoscape, marked, and DOMPurify from a CDN. So the rule is no
-longer *only serve bundles you trust* — it is the ordinary care you would give any
+longer _only serve bundles you trust_ — it is the ordinary care you would give any
 document from a source you do not know.
 
 # Citations
 
 [1] [README.md — Server trust boundary](https://github.com/serradura/okf-gem/blob/main/README.md) — the two-defense summary.
-[2] [lib/okf/server/templates/graph.html.erb](https://github.com/serradura/okf-gem/blob/main/lib/okf/server/templates/graph.html.erb) — `json_for_script` and the `DOMPurify.sanitize(marked.parse(...))` render.
+[2] [lib/okf/server/graph/template.html.erb](https://github.com/serradura/okf-gem/blob/main/lib/okf/server/graph/template.html.erb) — `json_for_script` and the `DOMPurify.sanitize(marked.parse(...))` render.

data/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## [1.3.0] - 2026-07-12
+
+- The graph server page now emits link-preview metadata: Open Graph and Twitter
+  Card tags with a social image, plus `theme-color` and `color-scheme`, so a
+  shared `okf server` URL unfurls as a proper card in chat and social apps.
+- Docs: a themed README hero (light and dark), a GitHub social preview image,
+  and Website / Live demo / Claude Code plugin links.
+
 ## [1.2.0] - 2026-07-12
 
 - Claude Code plugin. The repository now doubles as a plugin marketplace:

data/README.md

@@ -1,12 +1,10 @@
 <p align="center">
-<h1 align="center">
-  <img src=".github/logo.svg" alt="" width="128"><br/>
-  <i>okf-gem</i>
-</h1>
-</p>
-
-<p align="center">
-  <i>A lightweight Ruby gem for OKF: author, curate, and serve bundles as an interactive graph.</i>
+  <a href="https://okfgem.com">
+    <picture>
+      <source media="(prefers-color-scheme: dark)" srcset=".github/hero-dark.png">
+      <img src=".github/hero-light.png" width="100%" alt="okf-gem: your project's knowledge as a living graph. A lightweight Ruby gem for the Open Knowledge Format that authors, curates, and serves bundles of Markdown + YAML as an interactive graph.">
+    </picture>
+  </a>
 </p>
 
 <p align="center">
@@ -19,6 +17,12 @@
   <a href="#claude-code-plugin"><img src="https://img.shields.io/badge/Claude%20Code-plugin-D97757" alt="Claude Code plugin"></a>
 </p>
 
+<p align="center">
+  <b><a href="https://okfgem.com">Website</a></b> &nbsp;·&nbsp;
+  <b><a href="https://demo.okfgem.com">Live demo</a></b> &nbsp;·&nbsp;
+  <b><a href="https://claude.okfgem.com">Claude Code plugin</a></b>
+</p>
+
 **okf-gem** — `okf` on RubyGems — reads, validates, lints, and serves
 **Open Knowledge Format (OKF)** v0.1 bundles: directories of Markdown files with YAML frontmatter that humans and agents read from one source. It does not define a new place to keep knowledge; it gives you leverage over knowledge that already lives as Markdown. Each file is a _concept_; a directory of them is a _bundle_.
 
@@ -33,7 +37,7 @@ Here is what it is able to do:
 <p align="center">
   <picture>
     <source media="(prefers-color-scheme: dark)" srcset=".github/overview-dark.png">
-    <img src=".github/overview.png" width="100%" alt="The companion agent skill authors and curates an OKF v0.1 bundle (Markdown + YAML). A pure model (Concept, Bundle, Graph) reads that bundle and feeds both the okf CLI (validate — legal per §9; lint — well-curated; server — explore) and a library API you embed in Ruby.">
+    <img src=".github/overview-light.png" width="100%" alt="The companion agent skill authors and curates an OKF v0.1 bundle (Markdown + YAML). A pure model (Concept, Bundle, Graph) reads that bundle and feeds both the okf CLI (validate — legal per §9; lint — well-curated; server — explore) and a library API you embed in Ruby.">
   </picture>
 </p>
 
@@ -194,7 +198,8 @@ serving 37 concepts at http://127.0.0.1:8808 (Ctrl-C to stop)
 </picture>
 
 _The graph server on this repo's own [`.okf`](.okf) bundle, with the
-`capabilities/graph-server` concept selected._
+`capabilities/graph-server` concept selected. Try it live at
+**[demo.okfgem.com](https://demo.okfgem.com)**._
 
 `graph` and `server` are best-effort (§9): a file with invalid frontmatter is
 skipped (and noted on stderr), not fatal, so one bad file never breaks the rest.

data/lib/okf/server/{templates/graph.html.erb → graph/template.html.erb}

@@ -1,9 +1,23 @@
 <!doctype html><html lang="en"><head><meta charset="utf-8">
 <meta name="viewport" content="width=device-width,initial-scale=1">
-<title>OKF — <%= escaped_name %></title>
+<title>OKF · <%= escaped_name %></title>
+<meta name="color-scheme" content="dark light">
+<meta name="theme-color" media="(prefers-color-scheme: dark)" content="#0f1115">
+<meta name="theme-color" media="(prefers-color-scheme: light)" content="#ffffff">
+<meta property="og:type" content="website">
+<meta property="og:site_name" content="OKF">
 <meta property="og:title" content="<%= og_title %>">
 <meta property="og:description" content="<%= og_desc %>">
-<meta property="og:type" content="website">
+<meta property="og:image" content="https://okfgem.com/og-demo.png">
+<meta property="og:image:type" content="image/png">
+<meta property="og:image:width" content="1200">
+<meta property="og:image:height" content="630">
+<meta property="og:image:alt" content="An interactive Open Knowledge Format knowledge graph.">
+<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.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. */
 (function(){try{var t=localStorage.getItem('okf-theme')||(matchMedia('(prefers-color-scheme:dark)').matches?'dark':'light');document.documentElement.setAttribute('data-theme',t);}catch(e){}})();</script>

data/lib/okf/server/graph.rb

@@ -3,7 +3,7 @@
 module OKF
   module Server
     # Renders an OKF::Bundle::Graph as the interactive graph page served by
-    # OKF::Server::App. The markup lives in templates/graph.html.erb; #render
+    # OKF::Server::App. The markup lives in graph/template.html.erb; #render
     # returns the HTML string.
     #
     # The page boots from a *minimal* payload — nodes carry only id + title, plus
@@ -17,7 +17,7 @@ module OKF
     # trust. The inline-<script> data is </script>-escaped by #json_for_script
     # (stdlib ERB does not auto-escape).
     class Graph
-      TEMPLATE = File.expand_path("templates/graph.html.erb", __dir__)
+      TEMPLATE = File.expand_path("graph/template.html.erb", __dir__)
       LAYOUTS = %w[cose concentric breadthfirst circle grid].freeze
 
       # Node-diameter range in px; the template scales within it by node degree.
@@ -55,7 +55,7 @@ module OKF
       end
 
       def og_title
-        html_escape("OKF — #{graph_name}")
+        html_escape("OKF · #{graph_name}")
       end
 
       def og_desc

data/lib/okf/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: okf
 version: !ruby/object:Gem::Version
-  version: 1.2.0
+  version: 1.3.0
 platform: ruby
 authors:
 - Rodrigo Serradura
@@ -102,8 +102,8 @@ files:
 - lib/okf/path.rb
 - lib/okf/server/app.rb
 - lib/okf/server/graph.rb
+- lib/okf/server/graph/template.html.erb
 - lib/okf/server/runner.rb
-- lib/okf/server/templates/graph.html.erb
 - lib/okf/skill.rb
 - lib/okf/skill/SKILL.md
 - lib/okf/skill/playbooks/consume.md