From 9873a039542644b7b35f68dedceb94433c347fd3 Mon Sep 17 00:00:00 2001
From: Yvette Carlisle <y@acg.box>
Date: Wed, 17 Jun 2026 13:31:24 +0800
Subject: [PATCH] {"schema":"decodex/commit/1","summary":"Standardize OKF prose
 capitalization","authority":"manual"}

---
 apps/decodex/src/docs_okf.rs             | 35 ++++++++++++++++++++++++
 apps/decodex/src/plugin_surface_tests.rs |  1 +
 docs/log.md                              |  2 ++
 docs/policy.md                           |  6 ++++
 plugins/decodex/references/docs-okf.md   |  1 +
 5 files changed, 45 insertions(+)

diff --git a/apps/decodex/src/docs_okf.rs b/apps/decodex/src/docs_okf.rs
index b4b7962d..39a62469 100644
--- a/apps/decodex/src/docs_okf.rs
+++ b/apps/decodex/src/docs_okf.rs
@@ -137,6 +137,7 @@ pub(crate) fn run_docs_check(root: &Path, scope: DocsCheckScope) -> Result<DocsC
 
 	if matches!(scope, DocsCheckScope::All | DocsCheckScope::Index) {
 		check_markdown_only(&files, &mut report);
+		check_acronym_capitalization(&files, &mut report);
 		check_concept_contracts(&files, &mut report);
 	}
 	if matches!(scope, DocsCheckScope::All | DocsCheckScope::Links) {
@@ -254,6 +255,23 @@ fn check_markdown_only(files: &[DocsFile], report: &mut DocsCheckReport) {
 	}
 }
 
+fn check_acronym_capitalization(files: &[DocsFile], report: &mut DocsCheckReport) {
+	for file in files.iter().filter(|file| is_markdown(&file.relative_path)) {
+		let Some(content) = file.content.as_deref() else {
+			continue;
+		};
+
+		if content.contains("Okf") {
+			report.issues.push(issue(
+				Some(file.relative_path.clone()),
+				String::from(
+					"use `OKF` in prose; lowercase `okf` is reserved for paths, slugs, tags, and URLs",
+				),
+			));
+		}
+	}
+}
+
 fn check_concept_contracts(files: &[DocsFile], report: &mut DocsCheckReport) {
 	for file in files.iter().filter(|file| is_concept_markdown(&file.relative_path)) {
 		report.concept_count += 1;
@@ -844,6 +862,23 @@ mod tests {
 		assert!(report.issues.iter().any(|issue| issue.message.contains("JSON artifacts")));
 	}
 
+	#[test]
+	fn docs_check_rejects_mis_capitalized_okf_acronym() {
+		let temp_dir = TempDir::new().expect("tempdir");
+		let docs = temp_dir.path().join("docs");
+
+		write_minimal_okf_bundle(&docs);
+		write(
+			&docs.join("policy.md"),
+			"---\ntype: Policy\ntitle: Okf policy\ndescription: Test concept.\nstatus: active\nauthority: non_authoritative\nowner: docs\nlast_verified: 2026-06-16\n---\n\n# Purpose\nOkf should be uppercase.\n",
+		);
+
+		let report = docs_okf::run_docs_check(&docs, DocsCheckScope::All).expect("check");
+
+		assert!(report.has_issues());
+		assert!(report.issues.iter().any(|issue| issue.message.contains("use `OKF`")));
+	}
+
 	#[test]
 	fn docs_check_passes_minimal_okf_bundle() {
 		let temp_dir = TempDir::new().expect("tempdir");
diff --git a/apps/decodex/src/plugin_surface_tests.rs b/apps/decodex/src/plugin_surface_tests.rs
index 15c581ee..7581d112 100644
--- a/apps/decodex/src/plugin_surface_tests.rs
+++ b/apps/decodex/src/plugin_surface_tests.rs
@@ -307,6 +307,7 @@ fn packaged_docs_skills_encode_okf_wiki_and_drift_boundaries() {
 	assert_contains(&docs_surface, "one authoritative concept per claim");
 	assert_contains(&docs_surface, "pass`, `fail`, or `needs-human");
 	assert_contains(&docs_surface, "Do not create a parallel `wiki/` or `okf/` root");
+	assert_not_contains(&docs_surface, "Okf");
 }
 
 #[test]
diff --git a/docs/log.md b/docs/log.md
index ed400050..1fd660ff 100644
--- a/docs/log.md
+++ b/docs/log.md
@@ -35,3 +35,5 @@
 - Clarified the Program Intake public/private boundary so generated Linear issue
   descriptions omit internal Program and node identifiers while SQLite/operator
   readback keeps private mappings.
+- Standardized `OKF` as the all-caps prose form while preserving lowercase `okf` for
+  filenames, paths, skill IDs, tags, and URLs.
diff --git a/docs/policy.md b/docs/policy.md
index d6a0cf02..9eb1f49f 100644
--- a/docs/policy.md
+++ b/docs/policy.md
@@ -38,6 +38,12 @@ or private execution evidence.
 Runtime state may still use internal structured storage. The docs source of truth for
 research, drift audit, decisions, references, runbooks, and specs is Markdown.
 
+## Naming
+
+Write `OKF` as an all-caps acronym in prose, matching the repository convention for
+`CLI`. Lowercase `okf` is allowed only in machine identifiers such as filenames,
+paths, skill IDs, tags, and URLs.
+
 ## Concept Frontmatter
 
 Every concept must start with YAML frontmatter delimited by `---`.
diff --git a/plugins/decodex/references/docs-okf.md b/plugins/decodex/references/docs-okf.md
index c867abf4..3d04cbe8 100644
--- a/plugins/decodex/references/docs-okf.md
+++ b/plugins/decodex/references/docs-okf.md
@@ -10,6 +10,7 @@ concepts.
 - `docs/index.md`, `docs/policy.md`, and `docs/log.md` must exist.
 - Non-index, non-log Markdown documents are OKF concepts.
 - Concepts start with YAML frontmatter delimited by `---`.
+- Prose spells the acronym `OKF`; lowercase `okf` is slug-only.
 
 ## Required Frontmatter