Migrate the knowledge base to Open Knowledge Format (OKF) v0.1 - #11
Merged
Conversation
Migrate `insights/` to an OKF v0.1 bundle (spec: GoogleCloudPlatform/ knowledge-catalog). Mirrors the adoption in the sibling private-codex repo. Frontmatter (128 insight files, frontmatter-only — bodies untouched): - Add OKF reserved fields, reserved-first: `type: insight`, `resource` (the source URL), `timestamp` (git last-change date, ISO 8601). - Keep the existing `source:` block as a producer extension (medium, author, publication date). Handles both inline and block-list `tags` and single- and multi-source `source:` blocks. Structure: - Add an `index.md` tree (OKF §6) — bundle root (declares `okf_version: "0.1"`), per-category (blogs, podcasts), and per-collection indexes listing concepts as `* [Title](file.md) - desc`. - Add `log.md` change histories (OKF §7) at the bundle root and per collection — `# YYYY-MM-DD` headings, newest first. - Replace the old front-matter `37signals-rework/index.md` with an OKF one. - Remove the top-level `index.yml` (superseded by the `index.md` tree). - Update `README.md` (OKF format, cross-link, index/log conventions) and `insights/_template.md` to the OKF frontmatter. Cross-link unification (Obsidian `[[wikilinks]]` + prose references to standard Markdown relative links) follows in a separate PR.
There was a problem hiding this comment.
Pull request overview
This PR adopts the Open Knowledge Format (OKF) v0.1 for the curated insights bundle by introducing an OKF-compliant index/log structure and standardizing insight frontmatter across the insights tree, while removing the legacy index.yml.
Changes:
- Added OKF bundle root
index.md(withokf_version) and bundle/collectionlog.mdfiles. - Converted insight files to OKF-style frontmatter (
type: insight,resource,timestamp) while keepingsourceas an extension. - Replaced the previous unified
index.ymlwith an OKFindex.mdtree and updated contributor docs/templates.
Reviewed changes
Copilot reviewed 147 out of 147 changed files in this pull request and generated 3 comments.
Show a summary per file
| File | Description |
|---|---|
| README.md | Documents OKF bundle structure, conventions, and contributor workflow |
| log.md | Adds bundle-level change history (OKF §7) |
| index.md | Adds OKF bundle root index with okf_version: "0.1" (OKF §6) |
| index.yml | Removes legacy unified YAML index (superseded by index.md tree) |
| insights/_template.md | Updates canonical template to OKF frontmatter fields |
| insights/rails/index.md | Adds collection index listing Rails release highlight insights |
| insights/rails/log.md | Adds Rails collection change history |
| insights/rails/8_0_highlights.md | Updates insight frontmatter to OKF reserved fields |
| insights/rails/8_1_highlights.md | Updates insight frontmatter to OKF reserved fields |
| insights/rails/8_2_highlights.md | Updates insight frontmatter to OKF reserved fields |
| insights/podcasts/index.md | Adds category index listing podcast collections |
| insights/podcasts/rails-official/index.md | Adds collection index listing On Rails episode insights |
| insights/podcasts/rails-official/log.md | Adds On Rails collection change history |
| insights/podcasts/rails-official/ep01-rosa-gutierrez-solid-queue.md | Updates episode insight frontmatter to OKF reserved fields |
| insights/podcasts/rails-official/ep02-jean-boussier-io-bound-misconceptions.md | Updates episode insight frontmatter to OKF reserved fields |
| insights/podcasts/rails-official/ep03-nadia-odunayo-scaling-rails-for-millions-of-users.md | Updates episode insight frontmatter to OKF reserved fields |
| insights/podcasts/rails-official/ep04-ryan-stawarz-austin-story-doximity-rails-monolith.md | Updates episode insight frontmatter to OKF reserved fields |
| insights/podcasts/rails-official/ep05-hilary-stohs-krause-scaling-rails-with-small-wins.md | Updates episode insight frontmatter to OKF reserved fields |
| insights/podcasts/rails-official/ep06-florent-beaurain-optimizing-rails-tests-at-doctolib-scale.md | Updates episode insight frontmatter to OKF reserved fields |
| insights/podcasts/rails-official/ep07-alexander-stathis-scaling-modular-rails-monolith-angellist.md | Updates episode insight frontmatter to OKF reserved fields |
| insights/podcasts/rails-official/ep08-miguel-conde-peter-compernolle-gusto-rails-biolith.md | Updates episode insight frontmatter to OKF reserved fields |
| insights/podcasts/rails-official/ep09-kayla-reopelle-what-your-rails-app-is-trying-to-tell-you.md | Updates episode insight frontmatter to OKF reserved fields |
| insights/podcasts/rails-official/ep10-jay-tennier-rainforest-qa-tests-itself.md | Updates episode insight frontmatter to OKF reserved fields |
| insights/podcasts/rails-official/ep11-simone-carletti-rails-at-the-center-of-dnsimple.md | Updates episode insight frontmatter to OKF reserved fields |
| insights/podcasts/rails-official/ep12-brian-scanlan-building-ai-first-at-intercom.md | Updates episode insight frontmatter to OKF reserved fields |
| insights/podcasts/rails-official/ep13-jason-meller-rails-security-and-the-ai-advantage.md | Updates episode insight frontmatter to OKF reserved fields |
| insights/podcasts/rails-official/ep14-tom-rossi-staying-as-rails-as-possible.md | Updates episode insight frontmatter to OKF reserved fields |
| insights/podcasts/rails-official/ep15-dhh-basecamp-5-vibe-coding-and-the-future-of-rails.md | Updates episode insight frontmatter to OKF reserved fields |
| insights/podcasts/rails-official/ep16-nikky-southerland-lessons-from-13-years-of-rails-at-the-auto-shop.md | Updates episode insight frontmatter to OKF reserved fields |
| insights/podcasts/rails-official/ep17-bryce-harlan-a-decade-of-rails-in-healthcare.md | Updates episode insight frontmatter to OKF reserved fields |
| insights/podcasts/37signals-rework/index.md | Replaces prior frontmatter-heavy index with OKF index listing concepts |
| insights/podcasts/37signals-rework/log.md | Adds REWORK collection change history |
| insights/podcasts/37signals-rework/business-philosophy.md | Updates insight frontmatter to OKF reserved fields |
| insights/podcasts/37signals-rework/cloud-exit.md | Updates insight frontmatter to OKF reserved fields |
| insights/podcasts/37signals-rework/communication.md | Updates insight frontmatter to OKF reserved fields |
| insights/podcasts/37signals-rework/customer-support.md | Updates insight frontmatter to OKF reserved fields |
| insights/podcasts/37signals-rework/founder-leadership.md | Updates insight frontmatter to OKF reserved fields |
| insights/podcasts/37signals-rework/hiring.md | Updates insight frontmatter to OKF reserved fields |
| insights/podcasts/37signals-rework/marketing.md | Updates insight frontmatter to OKF reserved fields |
| insights/podcasts/37signals-rework/privacy-ethics.md | Updates insight frontmatter to OKF reserved fields |
| insights/podcasts/37signals-rework/product-development.md | Updates insight frontmatter to OKF reserved fields |
| insights/podcasts/37signals-rework/skipped-episodes.md | Updates insight frontmatter to OKF reserved fields |
| insights/podcasts/37signals-rework/work-culture.md | Updates insight frontmatter to OKF reserved fields |
| insights/podcasts/37signals-recordables/index.md | Adds RECORDABLES collection index listing concepts |
| insights/podcasts/37signals-recordables/log.md | Adds RECORDABLES collection change history |
| insights/podcasts/37signals-recordables/1-behind-the-fizzy-infrastructure.md | Updates insight frontmatter to OKF reserved fields |
| insights/podcasts/37signals-recordables/2-rails-multi-tenancy.md | Updates insight frontmatter to OKF reserved fields |
| insights/podcasts/37signals-recordables/3-moving-mountains-of-data-off-s3.md | Updates insight frontmatter to OKF reserved fields |
| insights/podcasts/37signals-recordables/4-rails-delegated-type-pattern.md | Updates insight frontmatter to OKF reserved fields |
| insights/podcasts/37signals-recordables/5-the-once-app-server.md | Updates insight frontmatter to OKF reserved fields |
| insights/blogs/index.md | Adds category index listing blog collections |
| insights/blogs/37signals/index.md | Adds collection index listing 37signals concept files |
| insights/blogs/37signals/log.md | Adds 37signals collection change history |
| insights/blogs/37signals/_manifesto.md | Updates insight frontmatter to OKF reserved fields |
| insights/blogs/37signals/_thoughts.md | Updates insight frontmatter to OKF reserved fields |
| insights/blogs/37signals/action-push-native.md | Updates insight frontmatter to OKF reserved fields |
| insights/blogs/37signals/better-navigation.md | Updates insight frontmatter to OKF reserved fields |
| insights/blogs/37signals/callbacks-and-current-attributes.md | Updates insight frontmatter to OKF reserved fields |
| insights/blogs/37signals/card-table-responsive.md | Updates insight frontmatter to OKF reserved fields |
| insights/blogs/37signals/cloud-exit.md | Updates insight frontmatter to OKF reserved fields |
| insights/blogs/37signals/concerns.md | Updates insight frontmatter to OKF reserved fields |
| insights/blogs/37signals/console-data-protection.md | Updates insight frontmatter to OKF reserved fields |
| insights/blogs/37signals/css-character-breakpoints.md | Updates insight frontmatter to OKF reserved fields |
| insights/blogs/37signals/css-custom-property-variants.md | Updates insight frontmatter to OKF reserved fields |
| insights/blogs/37signals/css-has-selector.md | Updates insight frontmatter to OKF reserved fields |
| insights/blogs/37signals/css-input-device-queries.md | Updates insight frontmatter to OKF reserved fields |
| insights/blogs/37signals/css-oklch-opacity.md | Updates insight frontmatter to OKF reserved fields |
| insights/blogs/37signals/data-infrastructure.md | Updates insight frontmatter to OKF reserved fields |
| insights/blogs/37signals/delegated-types-comparison.md | Updates insight frontmatter to OKF reserved fields |
| insights/blogs/37signals/development-environment.md | Updates insight frontmatter to OKF reserved fields |
| insights/blogs/37signals/domain-driven-naming.md | Updates insight frontmatter to OKF reserved fields |
| insights/blogs/37signals/faster-pagination.md | Updates insight frontmatter to OKF reserved fields |
| insights/blogs/37signals/fizzy-architecture.md | Updates insight frontmatter to OKF reserved fields |
| insights/blogs/37signals/fractal-code-quality.md | Updates insight frontmatter to OKF reserved fields |
| insights/blogs/37signals/fragment-capabilities.md | Updates insight frontmatter to OKF reserved fields |
| insights/blogs/37signals/gift-of-constraints.md | Updates insight frontmatter to OKF reserved fields |
| insights/blogs/37signals/homographic-spoofing.md | Updates insight frontmatter to OKF reserved fields |
| insights/blogs/37signals/hotwire-minimal-js.md | Updates insight frontmatter to OKF reserved fields |
| insights/blogs/37signals/hotwire-native-v1-2.md | Updates insight frontmatter to OKF reserved fields |
| insights/blogs/37signals/hotwire-spark.md | Updates insight frontmatter to OKF reserved fields |
| insights/blogs/37signals/imperative-infrastructure.md | Updates insight frontmatter to OKF reserved fields |
| insights/blogs/37signals/kamal-deployment.md | Updates insight frontmatter to OKF reserved fields |
| insights/blogs/37signals/lexxy-rich-text.md | Updates insight frontmatter to OKF reserved fields |
| insights/blogs/37signals/mission-control.md | Updates insight frontmatter to OKF reserved fields |
| insights/blogs/37signals/mission-control-jobs.md | Updates insight frontmatter to OKF reserved fields |
| insights/blogs/37signals/pr-review-practices.md | Updates insight frontmatter to OKF reserved fields |
| insights/blogs/37signals/prometheus-monitoring.md | Updates insight frontmatter to OKF reserved fields |
| insights/blogs/37signals/qa-practices.md | Updates insight frontmatter to OKF reserved fields |
| insights/blogs/37signals/query-objects.md | Updates insight frontmatter to OKF reserved fields |
| insights/blogs/37signals/radiating-programmer.md | Updates insight frontmatter to OKF reserved fields |
| insights/blogs/37signals/rails-multi-tenancy.md | Updates insight frontmatter to OKF reserved fields |
| insights/blogs/37signals/reliable-export-jobs.md | Updates insight frontmatter to OKF reserved fields |
| insights/blogs/37signals/ruby-memory-debugging.md | Updates insight frontmatter to OKF reserved fields |
| insights/blogs/37signals/solid-cache.md | Updates insight frontmatter to OKF reserved fields |
| insights/blogs/37signals/solid-queue.md | Updates insight frontmatter to OKF reserved fields |
| insights/blogs/37signals/testing-philosophy.md | Updates insight frontmatter to OKF reserved fields |
| insights/blogs/37signals/thruster.md | Updates insight frontmatter to OKF reserved fields |
| insights/blogs/37signals/turbo-8-morphing.md | Updates insight frontmatter to OKF reserved fields |
| insights/blogs/37signals/turbo-mobile.md | Updates insight frontmatter to OKF reserved fields |
| insights/blogs/37signals/turbo-progressive-enhancement.md | Updates insight frontmatter to OKF reserved fields |
| insights/blogs/37signals/upright-synthetic-monitoring.md | Updates insight frontmatter to OKF reserved fields |
| insights/blogs/37signals/vanilla-rails-stack.md | Updates insight frontmatter to OKF reserved fields |
| insights/blogs/37signals/yjit-performance.md | Updates insight frontmatter to OKF reserved fields |
| insights/blogs/evilmartians/index.md | Adds collection index listing Evil Martians concept files |
| insights/blogs/evilmartians/log.md | Adds Evil Martians collection change history |
| insights/blogs/evilmartians/2-martians-greenfield-to-mvp-in-4-weeks-agentic-coding-on-rails.md | Updates insight frontmatter to OKF reserved fields |
| insights/blogs/evilmartians/5-tips-for-activerecord-dashboards.md | Updates insight frontmatter to OKF reserved fields |
| insights/blogs/evilmartians/anycable-goes-pro-fast-websockets-for-ruby-at-scale.md | Updates insight frontmatter to OKF reserved fields |
| insights/blogs/evilmartians/anycable-rails-and-the-pitfalls-of-llm-streaming.md | Updates insight frontmatter to OKF reserved fields |
| insights/blogs/evilmartians/enter-anycable-v1-4-reliable-real-time-features-for-apps-of-any-size.md | Updates insight frontmatter to OKF reserved fields |
| insights/blogs/evilmartians/exploring-active-agent-or-can-we-build-ai-features-the-rails-way.md | Updates insight frontmatter to OKF reserved fields |
| insights/blogs/evilmartians/flying-free-a-tale-of-partitioning-with-canaries-in-postgresql.md | Updates insight frontmatter to OKF reserved fields |
| insights/blogs/evilmartians/gemfile-of-dreams-libraries-we-use-to-build-rails-apps.md | Updates insight frontmatter to OKF reserved fields |
| insights/blogs/evilmartians/hotwire-rails-summit-interactive-multi-step-forms-peak-ux.md | Updates insight frontmatter to OKF reserved fields |
| insights/blogs/evilmartians/hotwire-reactive-rails-with-no-javascript.md | Updates insight frontmatter to OKF reserved fields |
| insights/blogs/evilmartians/how-to-graphql-with-ruby-rails-active-record-and-no-n-plus-one.md | Updates insight frontmatter to OKF reserved fields |
| insights/blogs/evilmartians/it-deserved-its-own-tome-layered-design-and-the-extended-rails-way.md | Updates insight frontmatter to OKF reserved fields |
| insights/blogs/evilmartians/keeping-rails-cool-the-modern-frontend-toolkit.md | Updates insight frontmatter to OKF reserved fields |
| insights/blogs/evilmartians/logidze-1-0-active-record-postgresql-rails-and-time-travel.md | Updates insight frontmatter to OKF reserved fields |
| insights/blogs/evilmartians/martian-kubernetes-kit-a-smooth-sailing-toolkit-from-our-sre-team.md | Updates insight frontmatter to OKF reserved fields |
| insights/blogs/evilmartians/mrsk-hot-deployment-tool-or-total-game-changer.md | Updates insight frontmatter to OKF reserved fields |
| insights/blogs/evilmartians/now-you-see-it-vite-on-rails-without-the-proxy.md | Updates insight frontmatter to OKF reserved fields |
| insights/blogs/evilmartians/oklch-in-css-why-quit-rgb-hsl.md | Updates insight frontmatter to OKF reserved fields |
| insights/blogs/evilmartians/partition-and-conquer.md | Updates insight frontmatter to OKF reserved fields |
| insights/blogs/evilmartians/postgresql-and-rails-sitting-in-a-tree.md | Updates insight frontmatter to OKF reserved fields |
| insights/blogs/evilmartians/railing-against-time-tools-and-techniques-that-got-us-5x-faster-results.md | Updates insight frontmatter to OKF reserved fields |
| insights/blogs/evilmartians/rubanok-carve-your-rails-controllers-like-papa-carlo.md | Updates insight frontmatter to OKF reserved fields |
| insights/blogs/evilmartians/ruby-bytes-or-generating-standalone-generators.md | Updates insight frontmatter to OKF reserved fields |
| insights/blogs/evilmartians/ruby-on-rails-on-webassembly-a-guide-to-full-stack-in-browser-action.md | Updates insight frontmatter to OKF reserved fields |
| insights/blogs/evilmartians/ruby-on-whales-docker-for-ruby-rails-development.md | Updates insight frontmatter to OKF reserved fields |
| insights/blogs/evilmartians/simple-declarative-presence-for-hotwire-apps-with-anycable.md | Updates insight frontmatter to OKF reserved fields |
| insights/blogs/evilmartians/system-of-a-test-setting-up-end-to-end-rails-testing.md | Updates insight frontmatter to OKF reserved fields |
| insights/blogs/evilmartians/taking-off-the-heroku-training-wheels-the-rails-preflight-checklist.md | Updates insight frontmatter to OKF reserved fields |
| insights/blogs/evilmartians/test-prof-3-guided-and-automated-ruby-test-profiling.md | Updates insight frontmatter to OKF reserved fields |
| insights/blogs/evilmartians/test-prof-digest-2026-surprising-finds-from-30k-specs.md | Updates insight frontmatter to OKF reserved fields |
| insights/blogs/evilmartians/testprof-2-factory-therapy-for-your-ruby-tests-rspec-minitest.md | Updates insight frontmatter to OKF reserved fields |
| insights/blogs/evilmartians/testprof-a-good-doctor-for-slow-ruby-tests.md | Updates insight frontmatter to OKF reserved fields |
| insights/blogs/evilmartians/the-art-of-turbo-mount-hotwire-meets-modern-js-frameworks.md | Updates insight frontmatter to OKF reserved fields |
| insights/blogs/evilmartians/the-future-of-full-stack-rails-turbo-morph-drive.md | Updates insight frontmatter to OKF reserved fields |
| insights/blogs/evilmartians/the-joy-of-inertia-rails-painting-your-own-with-50-happy-little-lines.md | Updates insight frontmatter to OKF reserved fields |
| insights/blogs/evilmartians/the-whop-chop-how-we-cut-a-rails-test-suite-and-ci-time-in-half.md | Updates insight frontmatter to OKF reserved fields |
| insights/blogs/evilmartians/time-series-data-using-timescaledb-with-ruby-on-rails.md | Updates insight frontmatter to OKF reserved fields |
| insights/blogs/evilmartians/vite-lizing-rails-get-live-reload-and-hot-replacement-with-vite-ruby.md | Updates insight frontmatter to OKF reserved fields |
| insights/blogs/evilmartians/viewcomponent-in-the-wild-building-modern-rails-frontends.md | Updates insight frontmatter to OKF reserved fields |
| insights/blogs/evilmartians/viewcomponent-in-the-wild-embracing-tailwindcss-classes-and-html-attributes.md | Updates insight frontmatter to OKF reserved fields |
| insights/blogs/evilmartians/viewcomponent-in-the-wild-supercharging-your-components.md | Updates insight frontmatter to OKF reserved fields |
| insights/blogs/evilmartians/writing-custom-rubocop-rules-in-2026.md | Updates insight frontmatter to OKF reserved fields |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
|
|
||
| Useful as an input source of knowledge for AI coding agents (e.g. [Claude Code](https://docs.anthropic.com/en/docs/claude-code), [Agent OS](https://buildermethods.com/agent-os/concepts)), food for your [Second Brain](https://petermeglis.com/blog/unlock-your-brains-potential-a-beginners-guide-to-obsidian-and-building-a-second-brain/), or just for offline access. | ||
|
|
||
| The curated insights under [`insights/`](insights/) form an **[Open Knowledge Format (OKF)](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md) v0.1 bundle**: a directory tree of Markdown files with YAML frontmatter, one concept per file (`type: insight`), cross-linked and enumerated by `index.md` files — designed to be read by both humans and LLM/agent consumers. Start at [`/index.md`](index.md) (the bundle root) → a category/collection `index.md` → the individual insight files. The `references/` and `style-guide/` trees are mechanically extracted upstream docs and sit outside the OKF bundle. |
Owner
Author
There was a problem hiding this comment.
Fixed in commit 2e8dc6c: the intro now states the repository is an OKF bundle rooted at /index.md (which declares okf_version), with the insight concepts living under insights/. It no longer implies insights/ is itself the bundle root, resolving the contradiction.
| ### Insights | ||
| ### Insights (OKF bundle) | ||
|
|
||
| The `insights/` directory is an **[OKF](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md) v0.1 bundle** of curated knowledge distilled from blogs, podcasts, and official release notes. Unlike `references/`, this content is manually authored and committed directly. |
Owner
Author
There was a problem hiding this comment.
Fixed in commit 2e8dc6c: reworded this section to say insights/ holds the bundle's insight concepts while the bundle root is the repository's /index.md. The layout description and the bundle-root claim now agree.
| **Cross-links.** Concepts link to one another with **standard Markdown relative links** — `[text](other-file.md)` or `[text](../other-collection/file.md)` — which OKF reads as an (untyped) relationship whose meaning comes from the surrounding prose (OKF §5). Plain Markdown links render on GitHub and in Obsidian alike. | ||
|
|
||
| The `insights/` directory contains curated knowledge extracted from blogs, books, talks, podcasts, and courses. Unlike `references/`, this content is manually authored and committed directly. | ||
| **`index.md` and `log.md` (OKF §6–7).** The bundle root [`/index.md`](index.md) declares `okf_version: "0.1"` (the only place frontmatter is allowed in an index) and links the top categories. Each category and collection directory has an `index.md` (no frontmatter) listing its concepts as `* [Title](file.md) - description`. A `log.md` (bundle root + per collection) records change history, newest first, with `# YYYY-MM-DD` headings — populated from git history. Index and log files are (re)generated from the files + git history; don't hand-edit them. |
Owner
Author
There was a problem hiding this comment.
Fixed in commit 2e8dc6c: softened the wording to "generated from the insight files + git history with maintenance scripts rather than edited by hand." There is no committed in-repo generator command yet, so the text no longer implies one; the scripts live with the maintenance tooling.
Convert directional prose references between insight files into standard Markdown relative links — `[text](file.md)` (same collection) or `[text](../other/file.md)` (cross-collection) — which render on GitHub and in Obsidian and which OKF reads as untyped relationships. 69 links across 41 files, added by a per-collection pass: - blogs/37signals (15), blogs/evilmartians (8), podcasts/rails-official (23), podcasts/37signals-recordables (11), rails (7), and the 37signals-rework skipped-episodes tracker (5). Only genuine directional references to an existing insight file were linked — conservatively, one link per nearby context. Source-blog/ episode sections, external books/URLs/gems with no insight file, generic inline concept names, and code spans were left as-is. Backticked filename references (e.g. `domain-driven-naming.md`) were converted to readable links. Every `](*.md)` link resolves; none sit inside a code fence.
romansklenar
marked this pull request as draft
July 17, 2026 06:13
The 'not to founder-leadership.md' reference is exclusionary; linking it read as pointing the reader there, the opposite of the sentence's intent. Revert that one to a plain code-span filename (the other four positive 'already in X' references stay linked).
Address Copilot review on PR #11: - State the OKF bundle is rooted at the repository's /index.md (which declares okf_version), with insight concepts living under insights/ — removing the 'bundle is insights/' vs 'bundle root is /index.md' ambiguity in the intro and the Insights section. - Soften the index/log regeneration note: generated with maintenance scripts rather than implying an in-repo command that doesn't exist.
Removing the top-level index.yml (OKF migration) left the mechanically extracted references/ and style-guide/ trees without any index. Restore coverage with auto-generated navigation indexes that stay current with `make references` / `make style-guide`: - bin/generate_indexes.py — walks references/ (grouped by area/subdir, titles from Setext or ATX H1, else titleized filename) and style-guide/, emitting plain-Markdown index.md navigation files (not OKF concepts). - Makefile: new `references-index` / `style-guide-index` targets, wired into `references` / `style-guide`. - references/index.md (181 docs) and style-guide/index.md (6 guides), linked from the bundle root /index.md under a "Reference material" section. - README documents the generated indexes; .gitignore excludes tmp/ scratch/.
It's Rails Codex, not Django Codex — port bin/generate_indexes.py to bin/generate_indexes.rb (Makefile now calls `ruby`). Also fix the title extraction: Kamal docs carry YAML frontmatter whose first lines are `# This file has been generated ...` comments, which the old heading scan mistook for the H1. Now read the frontmatter `title:` first (falling back to the body's ATX/Setext heading, then a titleized filename), and prefix titles with their subsection when an area spans several (e.g. "Configuration: Accessories", "Commands: Deploy") while single-subsection areas like Rails Guides stay unprefixed.
Address Copilot review on PR #11: - Titleize known acronyms (RSpec, CSS, HTML, API, SQL, ...) so the style-guide index shows 'RSpec Style Guide', not 'Rspec'. - Disambiguate duplicate labels within an area by falling back to the titleized filename — Kamal's commands/docs.md and commands/help.md both carry 'title: Help' upstream, so docs.md now reads 'Commands: Docs'.
romansklenar
commented
Jul 17, 2026
Comment on lines
+193
to
+209
| * [This file has been generated from the Kamal source, do not edit directly.](kamal/docs/configuration/accessories.md) | ||
| * [This file has been generated from the Kamal source, do not edit directly.](kamal/docs/configuration/aliases.md) | ||
| * [Anchors](kamal/docs/configuration/anchors.md) | ||
| * [This file has been generated from the Kamal source, do not edit directly.](kamal/docs/configuration/booting.md) | ||
| * [Builder examples](kamal/docs/configuration/builder-examples.md) | ||
| * [This file has been generated from the Kamal source, do not edit directly.](kamal/docs/configuration/builders.md) | ||
| * [Cron](kamal/docs/configuration/cron.md) | ||
| * [This file has been generated from the Kamal source, do not edit directly.](kamal/docs/configuration/docker-registry.md) | ||
| * [This file has been generated from the Kamal source, do not edit directly.](kamal/docs/configuration/environment-variables.md) | ||
| * [This file has been generated from the Kamal source, do not edit directly.](kamal/docs/configuration/logging.md) | ||
| * [This file has been generated from the Kamal source, do not edit directly.](kamal/docs/configuration/output.md) | ||
| * [This file has been generated from the Kamal source, do not edit directly.](kamal/docs/configuration/overview.md) | ||
| * [This file has been generated from the Kamal source, do not edit directly.](kamal/docs/configuration/proxy.md) | ||
| * [This file has been generated from the Kamal source, do not edit directly.](kamal/docs/configuration/roles.md) | ||
| * [This file has been generated from the Kamal source, do not edit directly.](kamal/docs/configuration/servers.md) | ||
| * [This file has been generated from the Kamal source, do not edit directly.](kamal/docs/configuration/ssh.md) | ||
| * [This file has been generated from the Kamal source, do not edit directly.](kamal/docs/configuration/sshkit.md) |
| @@ -0,0 +1,7 @@ | |||
| # 2026-07-17 | |||
| - **Adopted** the Open Knowledge Format (OKF) v0.1 across the bundle — OKF reserved frontmatter (`type`, `resource`, `timestamp`) on all 128 insight files, an `index.md` tree replacing the top-level `index.yml`, per-collection and bundle-level `log.md`, and updated `README.md` and `_template.md`. | |||
Owner
Author
There was a problem hiding this comment.
Reconciled by fixing the PR description, not the log. log.md's "128 insight files" is the correct count — these are the 128 insight concept files (type: insight). The PR description's "129" was a raw git diff file count that also included the insights/_template.md rewrite; since the template now carries type: insight too, it slipped into the tally. _template.md is the OKF template, not an insight concept, so the accurate figure is 128 — the PR description now says 128 to match. The log entry is a point-in-time changelog, so a concrete count is appropriate there.
romansklenar
changed the title
v0.1
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Goal
Adopt the Open Knowledge Format (OKF) v0.1 for the curated
insights/knowledge base: OKF reserved frontmatter on every insight file, anindex.mdprogressive-disclosure tree, per-collectionlog.mdchange histories, and standard Markdown cross-links between concepts. The result is a spec-conformant bundle that reads cleanly for both humans and LLM/agent consumers.Motivation
Mirrors the OKF adoption already done in the sibling
private-codexrepo, so both halves of the Second Brain share one machine-readable format. The previous top-levelindex.ymlwas a bespoke index; OKF replaces it with a standard, self-describingindex.md/log.mdtree and a documented frontmatter schema.Summary
Frontmatter (128 insight files — frontmatter-only, bodies byte-identical vs.
main):type: insight,resource(source URL),timestamp(git last-change date, ISO 8601).source:block as a producer extension. Handles inline and block-listtags, and single- and multi-sourcesource:(e.g.solid-queuecites two posts as a YAML list).Structure (OKF §6–7):
index.mdtree: bundle root (okf_version: "0.1"), per-category (blogs,podcasts) and per-collection indexes listing concepts as* [Title](file.md) - description.log.mdchange histories at the bundle root and per collection (# YYYY-MM-DD, newest first).37signals-rework/index.mdwith an OKF one; remove the top-levelindex.yml.README.md(OKF format, cross-link, and index/log conventions) andinsights/_template.md.Cross-links (OKF §5):
[text](file.md)/[text](../other/file.md). 68 links across 41 files, added by a conservative per-collection pass (one link per nearby context; source sections, external books/gems, generic concept names, and code spans left as-is).Reference material indexes (replaces index.yml's
references:/style-guide:coverage):index.ymlalso indexed the mechanically-extractedreferences/andstyle-guide/trees. Restore that with Makefile-generated navigation indexes:bin/generate_indexes.rb(Ruby) emitsreferences/index.md(181 docs, grouped by area, subsection-prefixed titles) andstyle-guide/index.md(6 guides), wired intomake references/make style-guideso they stay current on submodule updates. Linked from the bundle root/index.mdunder a "Reference material" section. These are plain-Markdown nav files, not OKF concepts.Test plan
type: insight, plusresourceandtimestamp; frontmatter parses as YAML (inline/block tags, mapping/listsource).main.index.mdfiles carry no frontmatter except the bundle root'sokf_version; no index listsindex.md/log.md; each collection index enumerates 100% of its files.log.mdfiles: no frontmatter,# YYYY-MM-DDheadings, newest first.](*.md)link resolves to an existing tracked file (insight cross-links +references/index.md's 181 entries, 0 broken); none inside a fenced code block; cross-link diff is pure link-wrapping.make references-index/make style-guide-indexregeneratereferences/index.md/style-guide/index.md; root/index.mdlinks to both.index.ymlremoved; no tracked file references it (Makefile never did)./index.md, a couple of collectionindex.md/log.md, andreferences/index.mdon GitHub and in Obsidian to confirm links resolve in both.