From fadd2725fa7557f70f7092b0f00358023adee929 Mon Sep 17 00:00:00 2001
From: gsdali <51393997+gsdali@users.noreply.github.com>
Date: Sat, 27 Jun 2026 07:22:58 +1000
Subject: [PATCH 1/2] docs(okf): add mandatory context-first docs policy

Adds okf/policies/context-first.md (ecosystem standard: query the context MCP for OCCT/OCCTSwift docs before relying on training data) and links it from okf/index.md. Per SecondMouseAU/ecosystem OKF-STANDARD.md.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 okf/index.md                  |  4 ++++
 okf/policies/context-first.md | 26 ++++++++++++++++++++++++++
 2 files changed, 30 insertions(+)
 create mode 100644 okf/policies/context-first.md

diff --git a/okf/index.md b/okf/index.md
index e694e46..2d5576d 100644
--- a/okf/index.md
+++ b/okf/index.md
@@ -42,3 +42,7 @@ licensing (LGPL-2.1 + OCCT exception).
 - Consumable via direct link, CMake `add_subdirectory` / imported target, or runtime
   `dlopen` / `LoadLibrary`.
 - A Pascal binding (`pascal/occt_templot.pas`) ships alongside the C header.
+
+## Policies
+
+- [Query `context` first for OCCT / OCCTSwift docs](policies/context-first.md)
diff --git a/okf/policies/context-first.md b/okf/policies/context-first.md
new file mode 100644
index 0000000..428fa8c
--- /dev/null
+++ b/okf/policies/context-first.md
@@ -0,0 +1,26 @@
+---
+type: policy
+title: Query `context` first for OCCT / OCCTSwift docs
+description: Agents must consult the context MCP for OCCT/OCCTSwift APIs before relying on training data.
+tags: [policy, docs, context, agents]
+timestamp: 2026-06-27
+---
+
+# Query `context` first
+
+When answering or writing code that touches **OCCT** or the **OCCTSwift** API, you **MUST** consult the
+`context` MCP before relying on training-data recall of OCCT/OCCTSwift signatures — it is stale and
+wrong for this fast-moving stack.
+
+Use `mcp__context__get_docs(library=…, topic=…)` with:
+
+- **`occt`** — the underlying OpenCASCADE kernel (V8_0_0_p1 overview / user guides).
+- **`occtswift`** — the Swift wrapper API.
+- **this repo's own package** — its `context` library, where indexed.
+
+The reference manual (per-class Doxygen API) is not indexed: read the bundled
+`OCCT.xcframework/.../Headers/*.hxx`, or WebFetch `dev.opencascade.org/doc/refman/html/class_*.html`
+for a specific class.
+
+Ecosystem standard — see
+[OKF-STANDARD.md](https://github.com/SecondMouseAU/ecosystem/blob/main/OKF-STANDARD.md).

From 645492b1475ff1036cec88511cf258932886640d Mon Sep 17 00:00:00 2001
From: gsdali <51393997+gsdali@users.noreply.github.com>
Date: Sat, 27 Jun 2026 09:05:52 +1000
Subject: [PATCH 2/2] docs(okf): docs-lookup hierarchy + mandatory
 docs-currency policy

context-first.md becomes a lookup order (context for ecosystem -> context7 for external -> other repos' docs fallback); adds docs-current.md (docs update every release, or every PR for pre-semver repos).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 okf/index.md                  |  1 +
 okf/policies/context-first.md | 27 +++++++++++++++------------
 okf/policies/docs-current.md  | 21 +++++++++++++++++++++
 3 files changed, 37 insertions(+), 12 deletions(-)
 create mode 100644 okf/policies/docs-current.md

diff --git a/okf/index.md b/okf/index.md
index 2d5576d..b388ccf 100644
--- a/okf/index.md
+++ b/okf/index.md
@@ -46,3 +46,4 @@ licensing (LGPL-2.1 + OCCT exception).
 ## Policies
 
 - [Query `context` first for OCCT / OCCTSwift docs](policies/context-first.md)
+- [Documentation updates are mandatory](policies/docs-current.md)
diff --git a/okf/policies/context-first.md b/okf/policies/context-first.md
index 428fa8c..a9fdc8c 100644
--- a/okf/policies/context-first.md
+++ b/okf/policies/context-first.md
@@ -1,24 +1,27 @@
 ---
 type: policy
-title: Query `context` first for OCCT / OCCTSwift docs
-description: Agents must consult the context MCP for OCCT/OCCTSwift APIs before relying on training data.
-tags: [policy, docs, context, agents]
+title: Documentation lookup — `context` first
+description: Look docs up via context (ecosystem), context7 (external), then other repos' docs — never training-data recall.
+tags: [policy, docs, context, context7, agents]
 timestamp: 2026-06-27
 ---
 
-# Query `context` first
+# Documentation lookup — `context` first
 
-When answering or writing code that touches **OCCT** or the **OCCTSwift** API, you **MUST** consult the
-`context` MCP before relying on training-data recall of OCCT/OCCTSwift signatures — it is stale and
-wrong for this fast-moving stack.
+When answering or writing code that touches **OCCT** or the **OCCTSwift** API, you **MUST** look the
+documentation up rather than relying on training-data recall of OCCT/OCCTSwift signatures — it is
+stale and wrong for this fast-moving stack.
 
-Use `mcp__context__get_docs(library=…, topic=…)` with:
+**Lookup order:**
 
-- **`occt`** — the underlying OpenCASCADE kernel (V8_0_0_p1 overview / user guides).
-- **`occtswift`** — the Swift wrapper API.
-- **this repo's own package** — its `context` library, where indexed.
+1. **`context` MCP** (`mcp__context__get_docs`) — the primary source for all ecosystem docs:
+   `occt` (the OpenCASCADE kernel, V8_0_0_p1 overview), `occtswift` (the Swift wrapper), this repo's
+   own package, and the other OCCTSwift-family packages indexed there.
+2. **context7** — for **external** / third-party libraries that aren't in the local `context` cache.
+3. **Docs in the other ecosystem repos** (their `okf/`, `docs/`, READMEs) — the fallback when a topic
+   isn't indexed in either.
 
-The reference manual (per-class Doxygen API) is not indexed: read the bundled
+The OCCT reference manual (per-class Doxygen API) is not indexed: read the bundled
 `OCCT.xcframework/.../Headers/*.hxx`, or WebFetch `dev.opencascade.org/doc/refman/html/class_*.html`
 for a specific class.
 
diff --git a/okf/policies/docs-current.md b/okf/policies/docs-current.md
new file mode 100644
index 0000000..4ba6cfd
--- /dev/null
+++ b/okf/policies/docs-current.md
@@ -0,0 +1,21 @@
+---
+type: policy
+title: Documentation updates are mandatory
+description: Docs must be updated with every release — or every PR for repos not yet on stable semver.
+tags: [policy, docs, release, semver]
+timestamp: 2026-06-27
+---
+
+# Documentation updates are mandatory
+
+Documentation — the `context`-indexed docs, this repo's `okf/` bundle, and any public API reference —
+must not drift from the code:
+
+- **Repos on stable semver (≥ 1.0):** every **release** must ship the matching documentation update.
+  A release that changes public API or behaviour without updating the docs is incomplete.
+- **Repos not yet on semver (0.x / pre-release / untagged):** every **PR** that changes public API or
+  behaviour must update the docs in the same PR.
+
+This is the other half of the [`context-first`](context-first.md) contract: agents query the
+`context` docs (`occt`, `occtswift`, this package) as the source of truth, so those docs must be
+current — stale docs are worse than none.