okforge 0.6.2__py3-none-any.whl

okforge-0.6.2.dist-info/METADATA

@@ -0,0 +1,144 @@
+Metadata-Version: 2.4
+Name: okforge
+Version: 0.6.2
+Summary: okforge: a local-first LLM knowledge-base engine
+Project-URL: Repository, https://github.com/okforge/okforge
+Project-URL: Homepage, https://github.com/okforge/okforge
+Project-URL: Issues, https://github.com/okforge/okforge/issues
+Author: designcomputer
+License: Apache-2.0
+License-File: LICENSE
+Keywords: agents,ai,document,knowledge-base,llm,pageindex,rag,retrieval
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Requires-Dist: click==8.4.0
+Requires-Dist: json-repair==0.59.10
+Requires-Dist: litellm==1.87.2
+Requires-Dist: openai-agents==0.17.3
+Requires-Dist: pageindex==0.3.0.dev1
+Requires-Dist: portalocker==3.2.0
+Requires-Dist: prompt-toolkit==3.0.52
+Requires-Dist: python-dotenv==1.2.2
+Requires-Dist: pyyaml==6.0.3
+Requires-Dist: rich==15.0.0
+Requires-Dist: trafilatura==2.0.0
+Requires-Dist: watchdog==6.0.0
+Provides-Extra: dev
+Requires-Dist: mypy==1.15.0; extra == 'dev'
+Requires-Dist: pytest-asyncio==1.3.0; extra == 'dev'
+Requires-Dist: pytest==9.0.3; extra == 'dev'
+Requires-Dist: ruff==0.9.7; extra == 'dev'
+Requires-Dist: types-pyyaml==6.0.12.20260518; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# okforge
+
+A local-first LLM knowledge-base engine. Point it at your documents;
+it builds an interlinked wiki — per-document summaries, cross-document
+concept and entity pages, extracted images, and real page citations
+back to source. The wiki is plain Markdown with YAML frontmatter,
+readable in Obsidian or any editor, and queryable from a CLI, a chat
+REPL, or any MCP client.
+
+## Why
+
+Most retrieval setups hand an LLM a pile of raw chunks and hope. okforge
+instead compiles your sources into curated pages *ahead of time* —
+concepts and entities that already synthesize what's spread across
+many documents, each claim traceable back to a `(p. N)` citation in
+the original source. That matters most for models with limited
+context, including small models running entirely on your own hardware:
+they don't have to reconstruct an answer from scratch every query, and
+what they do say is checkable against a specific page, not just
+plausible-sounding.
+
+The output follows the [Open Knowledge Format (OKF)](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md) —
+typed frontmatter, relative links, a predictable directory layout — so
+the wiki a KB produces is portable, not locked to okforge itself.
+
+## Install
+
+```bash
+pip install git+https://github.com/okforge/okforge@main
+```
+
+## Quick start
+
+```bash
+mkdir my-kb && cd my-kb
+okforge init          # scaffold raw/, wiki/, .openkb/  (--json for scripts)
+okforge add paper.md  # ingest (pre-convert non-md/pdf inputs first)
+okforge query "What does the paper conclude?"
+okforge chat          # interactive REPL over the wiki
+okforge list --json   # machine-readable state (also: status, okf-lint)
+okforge describe "One line about this project."   # curated description
+```
+
+Non-Markdown, non-PDF inputs (docx, pptx, scans, photo catalogs, …)
+need converting to Markdown first, by a tool that understands your
+material — a page-aware OCR script, for example. A sibling
+`<doc>.pages.json` page array is what enables real `(p. N)` citations
+in the generated summaries.
+
+The query agent reads curated pages first, then drills for detail with
+a built-in `grep_wiki` lexical search (locate-then-read) rather than
+re-embedding everything. `okf-lint` checks a wiki bundle's OKF
+conformance.
+
+Configuration lives in `.openkb/config.yaml` (model, language, entity
+types, …) and `~/.config/openkb/global.yaml` (KB registry, default
+KB). The LLM endpoint is configured litellm-style — any
+OpenAI-compatible server works, including a local llama.cpp instance.
+
+### Topic tree (experimental, per-KB opt-in)
+
+For knowledge bases that outgrow a flat concept list: set
+`topic_tree: true` in `.openkb/config.yaml`, then run `okforge
+reindex`. Existing concepts cluster into named `concepts/<topic>/`
+directories, each with a `_topic.md` summary node; later ingests place
+new concepts by tree descent, and queries gain a `read_topic`
+navigation tool for browsing top-down instead of scanning a flat list.
+
+## Wiki layout
+
+```
+wiki/
+  index.md              # document + concept index
+  summaries/<doc>.md    # per-document summary (page citations when available)
+  concepts/<name>.md    # cross-document concept pages
+  entities/<name>.md    # named people/places/organizations/works
+  sources/<doc>.md      # ingested source text
+  sources/<doc>.json    # per-page text + images (when page-aware)
+  sources/images/<doc>/ # extracted images
+  log.md                # append-only ingest log
+```
+
+## Development
+
+```bash
+uv run --extra dev python -m pytest tests/   # test suite
+uv run --extra dev ruff check openkb tests   # lint
+uv run --extra dev ruff format openkb tests  # format
+```
+
+## Origins
+
+okforge began as a hard fork of [VectifyAI/OpenKB](https://github.com/VectifyAI/OpenKB),
+in the spirit of Karpathy's LLM-wiki idea, and has since diverged
+deliberately rather than tracking it — local-only by default, its own
+document-conversion boundary, and OKF conformance as a first-class
+goal rather than an incidental format.
+
+## License
+
+Apache-2.0. Portions originate from the upstream OpenKB project
+(copyright the original authors); okforge-specific changes are
+maintained at [okforge/okforge](https://github.com/okforge/okforge).

okforge-0.6.2.dist-info/RECORD

@@ -0,0 +1,54 @@
+openkb/__init__.py,sha256=0Sb2HnBQ4OKYPL88QXkVf4dSQHIT0IC2GNQuuqsU7j4,450
+openkb/__main__.py,sha256=lLkF5bqDRrywM-WEwoCLp185CyEL7kyeG_YZ7IR54ds,88
+openkb/cli.py,sha256=y1SbLkt1pKpgLfeygQK6QpXymTfW2XTjTDSZTfl9Vvk,109718
+openkb/config.py,sha256=wfNd59gJ290U7qIv6QcadaFTLDgoDH-ize-4isIcygk,11754
+openkb/converter.py,sha256=ZCqC9XNWBjT54ynws4aTbT_fM4rUNbGwx5SJqJE8BQc,10768
+openkb/frontmatter.py,sha256=KvYOVkDesPOuz7oGdlt0L13r3hzFf0Kj3_3ZrK_JQnM,4871
+openkb/images.py,sha256=xs2sT8ZsHnvbLItIlMQwLY86QcHQRgw0jQos-udj8z4,10344
+openkb/indexer.py,sha256=Wh_KNFyhTshGsSUQGZtw6MXfUYzbJ6_dA-_BXVLYG34,6556
+openkb/links.py,sha256=Z7leVXVILjXYD3M3ZieGm1yZhSRBuiyH09WzOu6XDVQ,3470
+openkb/lint.py,sha256=6qPgktbKgIsyvOin4O3yMI9Jj1r1ImuKqbR1XC_Jt1A,25601
+openkb/locks.py,sha256=C-TvU_Lh6uiAzmBtW0wIzD4kRxsd0l0AKTLqgTYY6xY,8102
+openkb/log.py,sha256=lojwiE_4FQU3zFUd9KpnZHpnF_ZOtHW3BKGePWlYdfo,696
+openkb/mutation.py,sha256=DxgqeneYPsOmuUcohvDfgzs5mWA5gY1Tiqbqs4hug3U,19906
+openkb/okf.py,sha256=ZaaY_6dD0mtyQbOE0TKuqQk_EfqZPjRB69Y7XnlRTVs,4755
+openkb/schema.py,sha256=0ewr9P1hHPknb-Ppf9PK_E6t7lwAXv8jXBNQSOQkyQI,4466
+openkb/state.py,sha256=3zvtDzGfZBqNqw6U_i2xvkaJEXERcOWSVGipkiTuSqo,4990
+openkb/topic_tree.py,sha256=T-5wKqyWnE40uxdGfPUucVN5KIQRRqMwNLtVfXcG87U,8783
+openkb/topic_tree_llm.py,sha256=SCq7wYaaymtCk2RyA3lBRVWqTZVetLkkiBuyDvKmlI8,3231
+openkb/tree_renderer.py,sha256=Ianh7iVU00UWekWtWMc32zjMP0_RgVW2rJ-xJ9K73Oc,6720
+openkb/url_ingest.py,sha256=2fbBGyoshy6tHTwlpme9R4sASbWI8pJNIwb5LWDiijw,10489
+openkb/visualize.py,sha256=X-QPmUwgTm4JXCdASu16u1msh8wGp-pXbIU4aaJx53Y,3070
+openkb/watcher.py,sha256=jj3pe_3kihQaBz2_ttirzY6JNg4YYd7qYKkBtNkpLWw,3318
+openkb/agent/__init__.py,sha256=LKcEDM1kfIRXjo-qW051lxpVqwxE0ViDrBw9rwjjV4s,75
+openkb/agent/_markdown.py,sha256=jAmosiPlmjnSZuEVA8Trb2yS6dQSpMtjctw6pcw3QNU,10751
+openkb/agent/chat.py,sha256=z7Zm616nM7K8R6NPR9yudfnb9Oz2NUGQvxFu19-PtvI,32480
+openkb/agent/chat_session.py,sha256=t84HVwhxFEOjTNNCiK3ij2wuWeBzJh4jKDKcyhG5YY4,8658
+openkb/agent/compiler.py,sha256=P_3bbKtJQOa-WGk6OOT8GTQQarhOK1x9yGvvEcxD61Y,95007
+openkb/agent/linter.py,sha256=LBLUqfrhlIm80uPlo2qR_zrZU9FRzvRGdsHcVKx1gA4,4312
+openkb/agent/query.py,sha256=wvOld-blIktK2fZ-G7_W6KwiAzxeJmhPAJO1tQubmRY,19211
+openkb/agent/skill_runner.py,sha256=n7C_OYPmNRjnA45xsfvRkvvfK_3zmbqosjZyuaK-k08,8577
+openkb/agent/skills.py,sha256=bP5SLi6tTv2NRybQ_TYdvu2iXVGVzQNhf5b_joJiHyw,4374
+openkb/agent/tools.py,sha256=-bGZU749xm-fCqMKuC3KU0t3Q5G-QZ9zw6nYiyV099U,15226
+openkb/deck/__init__.py,sha256=1DWI4g6n4TKwsXdICQJDwbUsOy0nU0AJJKOLQ-kG3rQ,1084
+openkb/deck/creator.py,sha256=OEYXhGormS_4umqn_inZKzrYm8mIvB2RQ_Diy0xQIoU,4383
+openkb/deck/validator.py,sha256=NPHeuK1dEuG3PNqksI9LVbcz7XHGnlR70EPOgntYRZY,9181
+openkb/prompts/__init__.py,sha256=DwUAzAi6-JsDFEqqbr52MR0S-GOf59adry1oj_ZaFNs,621
+openkb/prompts/skill_create.md,sha256=gM60bkCoNGjAMa-BxeQ35DIhK2WrecbsUKk4CIAsKto,9433
+openkb/skill/__init__.py,sha256=WjXlNxl5QpvSYf7zl6-3KWEwFB4SBVBalAQyODRCpjI,3401
+openkb/skill/creator.py,sha256=S9RauPFtj8OdmN3EBGCDsBrYnnoyBwjuFNhnMK9vnUQ,8294
+openkb/skill/evaluator.py,sha256=n_FkUgdRMYjrm7KRmeX6VeXqDieLTziwb1q7pyOFFFM,19702
+openkb/skill/generator.py,sha256=LH2IoqycN7q6hvBEpDDkDTAY0QmnipZ7-_qSFNzNSwg,4841
+openkb/skill/marketplace.py,sha256=5EtrI86MSd1tT3Wi86C9J_wwg-Eyj511q9GOArMav9k,4208
+openkb/skill/tools.py,sha256=FedIQhjK8mNxmzAe0hV412anLRFiecB_Zz6JBfPcfeM,3787
+openkb/skill/validator.py,sha256=eOACGe6OIP7kVouBHq9ebt2CHTUInTL21GvhSbLUGp8,10905
+openkb/skill/workspace.py,sha256=kdrmtL79RIRwpJNv5XJoeqfW39WSL-5mK-ZlS0e8PaY,6071
+openkb/templates/graph.html,sha256=YIfe1NOgPhfpj_BQ8rUMwnE4hHGbTt1EvP4caBa--TA,45993
+openkb/_skills/openkb-deck-editorial/SKILL.md,sha256=Zv3HYka3Jg5bLHbX7TS_7cy5wc3yUK0om3HAVPJVb7k,8454
+openkb/_skills/openkb-deck-neon/SKILL.md,sha256=neLaMmrthkV9rAbflZa7DcGVQFNTwMGExPmpGKpQIjk,17222
+openkb/_skills/openkb-html-critic/SKILL.md,sha256=FvVHURhg_NVE2N5zXKT3HuiE6Rblb06ekgakjpc6aF0,5606
+okforge-0.6.2.dist-info/METADATA,sha256=UAfjqo3Zum_Gorc7BALN14p543ht43_eHQQERExb0J0,5846
+okforge-0.6.2.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+okforge-0.6.2.dist-info/entry_points.txt,sha256=XklTsZ1nZA0oX_11QdzkXtHSuhKtnE56eBBIEd5tdM4,67
+okforge-0.6.2.dist-info/licenses/LICENSE,sha256=J6AWg5EfUKRAYbFR3gelkPflBxL_ipfRzf-cOVqNtzI,10761
+okforge-0.6.2.dist-info/RECORD,,

okforge-0.6.2.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.31.0
+Root-Is-Purelib: true
+Tag: py3-none-any

okforge-0.6.2.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+okforge = openkb.cli:cli
+openkb = openkb.cli:cli

okforge-0.6.2.dist-info/licenses/LICENSE

@@ -0,0 +1,190 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to the Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by the Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding any notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   Copyright 2026 Vectify AI
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

openkb/__init__.py

@@ -0,0 +1,13 @@
+"""OpenKB package (distributed as okforge; import package kept as openkb)."""
+
+from importlib.metadata import PackageNotFoundError
+from importlib.metadata import version as _version
+
+try:
+    __version__ = _version("okforge")
+except PackageNotFoundError:
+    # Fallback for environments still carrying the pre-fork distribution.
+    try:
+        __version__ = _version("openkb")
+    except PackageNotFoundError:
+        __version__ = "0.0.0+unknown"

openkb/__main__.py

@@ -0,0 +1,5 @@
+"""Allow running okforge as ``python -m openkb``."""
+
+from openkb.cli import cli
+
+cli()

openkb/_skills/openkb-deck-editorial/SKILL.md

@@ -0,0 +1,185 @@
+---
+name: openkb-deck-editorial
+description: |
+  Use when the user asks the openkb chat to make a deck / slide presentation /
+  PPT / slides / 演示稿 / 幻灯片 from their compiled KB content. Generates a
+  polished single-file HTML deck in the Editorial Monocle visual direction
+  (warm cream background, serif type, brick-red accent) — designed to be
+  opened in a browser, full-screened, and shared. Does NOT apply to
+  generating skills (that's `openkb skill new`), long-form research reports,
+  or interactive prototypes.
+od:
+  mode: deck
+  output_path_template: "output/decks/{slug}/index.html"
+  deck_grammar:
+    kind_attr: data-type
+    required: [cover, closing]
+    allowed: [cover, chapter, thesis, quote, compare, data, closing]
+    min_distinct: 4
+    max_consecutive_same: 2
+---
+
+# Editorial Monocle deck skill
+
+You are designing a presentation, not writing a research report. Each
+slide carries one idea. Visual structure carries the narrative.
+
+## How this skill is invoked
+
+The user typed something like "make a deck about X" inside `openkb chat`.
+You have wiki-read tools in your normal tool set, plus a `write_file`
+tool that can write under `output/**`, plus a shell tool you can use to
+read this SKILL.md and any files in `skills/openkb-deck-editorial/` if
+needed.
+
+Pick a kebab-case slug for the deck (e.g. `transformers-pitch`) and
+write the output to `output/decks/<slug>/index.html`.
+
+## Required output
+
+Exactly one file: `output/decks/<slug>/index.html`.
+
+It must be **self-contained**: no external `<link rel="stylesheet">`,
+no external `<script src="…">`, no remote `<img>`. All CSS goes in a
+single inline `<style>` in `<head>`. Helper JS for keyboard navigation
+goes in a single inline `<script>` at end of `<body>`.
+
+The body is a sequence of `<section class="slide" data-type="...">`
+blocks. Each `data-type` must be one of the 7 values listed in §
+"Slide grammar" below. The deck supports keyboard navigation: ← / →
+move between slides, `F` toggles fullscreen, `P` triggers print.
+
+## Design system: Editorial Monocle
+
+Use this fixed design system. Do not improvise nearby colors, do not
+introduce gradients, do not bring in emojis. This is the **only**
+non-monochrome palette in the entire deck.
+
+### Color palette
+
+```css
+:root {
+  --bg:        #f3eee1;  /* oklch(94% 0.03 80)  — warm cream paper */
+  --ink:       #1a1612;  /* oklch(15% 0.01 50)  — warm near-black */
+  --muted:     #7a6e55;  /* oklch(55% 0.04 75)  — labels / metadata */
+  --rule:      #d4cfc0;  /* oklch(82% 0.02 75)  — thin separator */
+  --accent:    #a4341c;  /* oklch(45% 0.16 30)  — brick red, the ONLY non-monochrome */
+  --highlight: #fff3a8;  /* oklch(95% 0.10 95)  — marker highlighter ONLY */
+}
+```
+
+### Type system
+
+```css
+font-family-serif:  "Charter", "Iowan Old Style", "Times New Roman", Georgia, serif;
+font-family-sans:   "Inter", -apple-system, "Helvetica Neue", sans-serif;  /* labels only */
+```
+
+Type scale (size / line-height / letter-spacing):
+
+* `--type-display`: 56px / 1.05 / -1px      — cover/chapter big titles
+* `--type-title`:   38px / 1.10 / -0.5px    — normal slide titles
+* `--type-body`:    18px / 1.55 / 0         — body copy
+* `--type-quote`:   28px / 1.30 / -0.3px    italic — pull quotes
+* `--type-label`:   10px / 1.0 / 2.5px      uppercase — top/bottom label tracks
+
+### Frame (every slide)
+
+* 16:9 aspect ratio: `aspect-ratio: 16/9; width: 100vw; max-width: 1280px;`
+* Per-slide padding: 64px top/bottom, 80px left/right.
+* **10px brick-red bar on the right edge of every slide.** The deck's
+  visual signature. 4px reads as invisible at presentation scale.
+* Top label row: left = chapter id (e.g. "CHAPTER 03"), right = source mark.
+* Bottom folio row: left = `N / Total`, right = source short label.
+
+### Composition rules
+
+* **Cover title (`.display`)** must use `max-width: 18ch` (NOT 10ch).
+  Never wrap an article ("the", "an", "to") onto its own line.
+* **Data slides** must center the big number horizontally on the slide
+  (`.data-body { align-items: center; text-align: center }` for
+  `data-type="data"` only — leave other slide types left-aligned).
+  Body copy beneath stays centered, max-width 38em.
+* **Cover and closing slides**: `.cover-body, .closing-body { max-width: 26em }`.
+
+### Keyboard nav hint
+
+```css
+.kbd { opacity: 0; transition: opacity .25s ease; }
+body:hover .kbd { opacity: .55; }
+```
+
+## Slide grammar (7 permitted `data-type` values)
+
+| `data-type` | Use | Visual signature |
+|---|---|---|
+| `cover`   | First slide: tag + huge title + 1-line subtitle | Display type, left-aligned, never centered |
+| `chapter` | Section divider: oversize number + chapter name | Number 120px brick-red, name 38px serif |
+| `thesis`  | A single claim + a short explanation | Title fills ~60% height, explanation small bottom |
+| `quote`   | Italic pull-quote + attribution | Centered, serif italic 28px, generous whitespace |
+| `compare` | Two-column comparison: header + 3-5 lines each side | 1px brick-red vertical rule between columns |
+| `data`    | One number + label + one-line interpretation | Number 120-160px brick-red, micro-copy 12px |
+| `closing` | Mirrors `cover`; thanks / next steps | Same scale as cover but content closes the arc |
+
+**Cover/closing exception:** the `cover` and `closing` slides have no
+chapter context, so the top-left label is the deck identifier
+("OPENKB") instead of a `CHAPTER NN` id.
+
+## Working method
+
+1. **Survey first.** Use your wiki-read tools to list `concepts/` and
+   `summaries/`, and read `wiki/index.md`. Form a mental map before
+   committing to what the deck argues.
+2. **Choose a narrative arc.** Write a one-line thesis, then an 8-12
+   step arc (problem → tension → resolution, or whatever shape the
+   intent calls for). Each step becomes 1-2 slides, landing the final
+   deck in the 8-15 range required by §Self-check.
+3. **Read the relevant content.** For each concept the arc touches,
+   read the concept page. For each document a concept cites, read at
+   least one targeted slice of the source. **This is where the
+   specific arguments, named techniques, worked examples, and
+   counter-cases live. The deck is only as expert as the depth of
+   source reading you do here. Generic restatements of the topic are
+   a failure mode — your deck will read as a definition-grade
+   summary, not an expert briefing.**
+4. **Outline the slides.** Map each step to one or more slides with
+   concrete `data-type` assignments. Vary `data-type` — at least 4
+   distinct types, no run of 3+ consecutive same type.
+5. **Write `output/decks/<slug>/index.html`** in one `write_file`
+   call. Inline all CSS, inline the keyboard nav JS, use inline
+   `<svg>` only for any graphics (v1 does not embed bitmap images).
+6. **Revise.** Re-read against §Failure modes below; touch at least
+   one slide if anything matches.
+7. **Self-check** the 5 invariants in §Self-check; fix anything that
+   fails.
+8. Report back to the user with: the deck path and a one-line summary
+   of the arc you chose.
+
+## Failure modes (negative checklist)
+
+1. **Bullet dump** — slide with > 5 bullet points. Cut to 3 strongest
+   or restructure into a `compare` / `data` slide.
+2. **Wall of text** — slide body > ~80 words. Cut, or split.
+3. **Visual monotony** — 3+ consecutive slides with the same `data-type`.
+4. **Centered everything** — only `quote` and `closing` are centered.
+5. **AI slop palette** — any color outside the 6-value palette: no
+   blue/purple gradients, no emoji, no rainbow accents.
+6. **Generic titles** — "Introduction" / "Background" / "Conclusion"
+   as a slide title. Title must carry specific content.
+7. **Definition-grade content** — slide body is just "X is Y where Y
+   is …" with no named technique, no number, no concrete example, no
+   quote from the source. If you can't name *something specific* on a
+   slide, the wiki may not have the depth — re-read the source pages
+   (step 3) before settling for a definition.
+
+## Self-check (before reporting back)
+
+1. Does `output/decks/<slug>/index.html` exist and contain no external
+   `<link>` or `<script src=>`?
+2. Is there at least one `data-type="cover"` and one
+   `data-type="closing"`?
+3. Is the total slide count between 8 and 15?
+4. Are at least 4 distinct `data-type` values used?
+5. Is there no run of 3+ consecutive slides with the same `data-type`?
+
+If any answer is no, revise and re-run this self-check.