docs(catalog): add OKF-compatible second-brain form spec + coordination log

Cross-cutting catalog artifact (owned by no single plugin): the shared
"OKF-compatible second-brain form" convention all three second-brain plugins
(linkedin-studio, okr, ms-ai-architect) conform to, plus a coordination log
that serves as the cross-repo rollout state.

- spec.md: minimal contract (type + per-level index.md + root okf_version),
  recommended fields, extension keys, reference checker (okr okf-check),
  verified premise corrections (mdcode != OKF tool; no reusable OKF ingest),
  staged plan, homes, versioning. linkedin-studio's brain = reference design;
  OKF = thin interop veneer.
- log.md: coordination protocol (single source of truth, no cross-repo writes,
  operator relay), per-plugin conformance status table, open coordination items.

linkedin-studio recorded conformant (brain emits OKF form, cross-tool-verified
against okr's okf-check). okr / ms-ai-architect rollout = separate per-repo go.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_012GqEHp4uDiivfrAUjw4BdE

docs/okf-second-brain/log.md

@@ -0,0 +1,69 @@
+# OKF second-brain convergence — coordination log
+
+> Cross-repo coordination for the OKF-compatible second-brain form (`spec.md`). This is the **one
+> shared place** all three plugin sessions read to know where the others are. OKF reserves `log.md`
+> for change logs; this extends it with rollout status + the coordination protocol.
+>
+> **No writing crosses repo boundaries** — each plugin session writes only its own repo (+ the catalog
+> with its own go). Status here is updated via operator relay.
+
+## Coordination protocol
+
+The operator runs one Claude session per plugin repo and relays between them. To keep three
+independent sessions converged **without** cross-repo writes (mirrors the maskinrommet feedback-register
+pattern):
+
+1. **Single source of truth = `spec.md`.** The convention is defined once, here. No plugin redefines it
+   locally; a plugin's local OKF doc *references* this file. (Mirrors the global rule: don't invent
+   local mechanisms; extend the shared one.)
+2. **This log is the cross-repo state.** Convention version, decisions, per-plugin conformance status,
+   open coordination items. All three sessions read it.
+3. **No writing crosses repo boundaries.** Each session writes only its own repo. The catalog is shared
+   but needs a per-session go. A plugin records its own conformance in its own STATE/changelog; the
+   operator relays it here.
+4. **Operator = relay + truth-source.** Convention changes are proposed by any session, written here
+   (with go), and the operator carries "convention changed → re-check conformance" to the other
+   sessions.
+5. **Two version markers** (spec §12): `okf_version` (upstream Google OKF) and this convention's own
+   version. Either bump → log it below → each plugin re-checks.
+
+## Per-plugin conformance status
+
+Legend: 🔵 not started · 🟡 building / partial · 🟢 conformant (+ commit-ref)
+
+| Plugin | Against minimal contract (spec §3) | Notes | Status |
+|---|---|---|---|
+| **linkedin-studio** | `type` + per-level `index.md` + root `okf_version` on `brain/`; `ingest/` excluded (round-trip-critical tributary) | Reference design. Emits frontmatter, adds no parser. Brain suite 134/134; okr's `okf-check` validates `brain/` → exit 0 (also mid-propose with a pending-diff present). | 🟢 @ linkedin-studio `da0a16a` (2026-06-26) |
+| **okr** | `type` required + recommended-as-warnings + `okf_version` echo | Has the reference **writer + checker** (`okf-check.mjs`, `okf-index.mjs`, `lib/frontmatter.mjs`) + skill `okr-second-brain-search` v1.6.1. Form-alignment to this spec = **separate go**. | 🟡 built; spec-alignment pending |
+| **ms-ai-architect** | designed, not built | Targets the fuller OKF package + a retrieval skill. Builds against this spec. **Separate go.** | 🔵 designed |
+
+## Open coordination items (what each session must confirm)
+
+**→ okr session:**
+- Confirm `okf-check.mjs` semantics are stable enough to stand as the reference contract (spec §3, §7),
+  and that this spec faithfully generalizes them (only-`type`-required; recommended → warnings;
+  `okf_version` echo).
+- Canonical recommended-field name is **`resource`** (OKF), not `source` — confirm okr uses `resource`.
+- Flag any field okr needs that the minimal contract + recommended set doesn't cover.
+
+**→ ms-ai-architect session:**
+- Confirm the minimal contract + extension-key model (spec §3, §5) supports the planned **"full OKF
+  package"** KB structure — going fuller is fine; the minimal contract is the **floor, not the ceiling**.
+- **Field-name drift:** the architect brief writes `source`/`timestamp` (line 45); canonical is OKF's
+  **`resource`**. Align on `resource`.
+- **mdcode is not an OKF tool** (spec §9.1) — drop it from the adoption plan. The `reference_agent`
+  enrichment is GCP/Gemini-bound (spec §9.2) — adopt the *prompt patterns*, not as drop-in code.
+
+**→ both:**
+- Ratify `spec.md` as the shared contract, or propose changes here.
+- Retrieval-skill naming/home: okr shipped `okr-second-brain-search`; architect plans
+  `second-brain-search`. If a shared skill ever happens (Stage 3), converge naming + home (standalone
+  plugin, spec §11) — **not now** (Stage 2 measurement must justify it first).
+
+## Change log
+
+- **2026-06-29** — Convention **v0.1** authored (`spec.md`) + this log. Seeded from the three per-plugin
+  design notes + linkedin-studio's verified premise corrections (mdcode ≠ OKF tool; no reusable OKF
+  ingest code; classify/convert is build-yourself). linkedin-studio recorded **🟢** (brain emits
+  OKF-compatible form, cross-tool-verified against okr's `okf-check`). okr / ms-ai-architect rollout =
+  separate per-repo go. _(Authored by the linkedin-studio session; operator relay to siblings pending.)_

docs/okf-second-brain/spec.md

@@ -0,0 +1,168 @@
+# OKF-compatible second-brain form
+
+A cross-plugin convention for how each plugin stores the **user's own context** — their
+personal/organizational "second brain" / LLM-wiki — as a portable, interoperable markdown
+bundle, compatible with Google's Open Knowledge Format (OKF) v0.1.
+
+> **Version 0.1 · 2026-06-29 · Cross-cutting catalog artifact, owned by no single plugin.**
+> Reference design: linkedin-studio's `brain/`. Interop layer: Google OKF v0.1 (thin veneer).
+> Change log + per-plugin rollout status + coordination protocol: `log.md` (same directory).
+
+## 1. Purpose & scope
+
+This convention exists for **interop**, not standard-adoption for its own sake. Three plugins in
+this marketplace independently grew a user-owned "second brain" — a wiki of the user's personal and
+organizational context the plugin retrieves from during chat and commands. This document defines the
+**one shared on-disk form** so a single reader can traverse all three, and so a future shared
+retrieval skill (if ever justified — §10) has one contract to build against.
+
+- **In scope:** the user's own context/data — the per-user second brain (e.g. `~/.claude/<plugin>/...`).
+- **Explicitly out of scope:** each plugin's **domain reference files** (skill `references/*`). Those
+  stay native Claude Code skill-references (Anthropic-recommended progressive disclosure). The decisive
+  test, which all three plugins reached independently: not "is it an LLM-wiki" (both are) but
+  **"is there already a native, recommended mechanism?"** — for skill-refs YES (skills + references +
+  grep), for the second brain NO (it lived in ad-hoc `org/*.md` with no retrieval mechanism). OKF fills
+  a real gap **only** for the second brain.
+
+## 2. The three consumers
+
+| Plugin | Second-brain maturity | Role here |
+|---|---|---|
+| **linkedin-studio** | Provenance-weighted learning system (episodic/semantic split, evidence-threshold promotion, temporal validity). Most mature. | **Reference design.** Siblings rise toward it; it is not levelled down to bare OKF. |
+| **okr** | Built: writer + checker (`okf-check.mjs`, `okf-index.mjs`) + retrieval skill `okr-second-brain-search`. | **Reference checker** (§7). |
+| **ms-ai-architect** | Designed, not built. Targets the fuller OKF package + a retrieval skill. | Builds against this spec. |
+
+Live rollout status (🔵/🟡/🟢 + commit-refs) lives in `log.md`, not here.
+
+## 3. Minimal contract (normative)
+
+A conforming **bundle** is a directory tree of markdown files, one concept per file. Concept ID =
+file path minus `.md`.
+
+- **MUST** — every concept file (every `.md` except `index.md`) carries a `type:` frontmatter key
+  (free string, e.g. `Profile`, `Operations`, `JournalEntry`).
+- **MUST** — every directory level has an `index.md` (directory enumeration, **no frontmatter**,
+  carries progressive-disclosure prose).
+- **MUST** — the bundle-root `index.md` carries an `okf_version` marker (the upstream OKF version the
+  bundle targets, currently `0.1`).
+- **MUST (consumers)** — preserve unknown frontmatter keys, tolerate unknown `type` values, tolerate
+  broken cross-links.
+
+This is exactly okr's `okf-check.mjs` semantics, generalized (§7).
+
+## 4. Recommended fields (warnings, not errors)
+
+`title`, `description`, `resource` (canonical source URI), `tags`, `timestamp`. Supply where cheap.
+
+- **Canonical name is `resource`** (the OKF spec's name) — **not** `source`.
+- A field that would break a plugin's invariant may be omitted. Example: linkedin-studio omits
+  `timestamp` (its serializer is pure/deterministic — a timestamp would break round-trip) and
+  `resource` (an internal concept has no canonical URI), keeping `type`/`title`/`description`.
+
+## 5. Extension keys — rich fields ride along
+
+OKF's permissiveness is the whole point for us: conforming costs `type` + `index.md`, nothing more. A
+plugin's richer schema survives untouched as **extension frontmatter keys** that consumers MUST
+preserve. linkedin-studio's brain keeps `provenance`, `first_seen`, `last_seen`, `evidence_count`,
+`status`, and its episodic/semantic split — all as extension keys. Its model-collapse guard
+(`provenance=published` only) is unaffected. **Plugins rise toward the richest design; they are not
+levelled down to bare OKF.**
+
+## 6. Reserved files & cross-links
+
+- `index.md` — directory enumeration, **no frontmatter**, progressive-disclosure prose. The
+  bundle-root one carries `okf_version`.
+- `log.md` — change log (optional per bundle; reserved name).
+- Cross-links — plain markdown (bundle-relative `/...` or relative); relation type conveyed by prose.
+  Consumers MUST tolerate broken links.
+
+## 7. Reference checker
+
+okr's `scripts/okf-check.mjs` is the de-facto reference implementation of the minimal contract (§3):
+only `type` required (missing → fail + names the files), recommended fields → warnings, root
+`index.md` `okf_version` echoed for human comparison (no network — hooks are offline). ~91 lines, zero
+npm dependencies, only couples to a ~55-line `frontmatter.mjs`. The shared spec **generalizes okr's
+semantics; it does not reinvent them.** Reading okr's code is fine; **writing okr is a separate go.**
+
+A **single shared checker** is a Stage-3 item (§10), deferred until measured need — note that
+linkedin-studio already has a parallel **TypeScript** conformance implementation (`scripts/brain/`), so
+a shared checker means reconciling two language implementations of the same convention. Cross-tool
+interop is already proven: okr's `okf-check.mjs` validates linkedin-studio's `brain/` → exit 0.
+
+## 8. Deliberately NOT mandated
+
+- **Auto-classify / convert** of arbitrary documents into the bundle — OKF provides nothing for it; a
+  manual inbox/drop-zone seam suffices; build only on demonstrated need.
+- **Retrieval mechanism** — native Grep/Glob/Read (skill instruction "search the wiki first, open only
+  what's relevant") vs. a dedicated fileskb MCP server. All three plugins lean **native** (Claude
+  Code's Grep/Glob/Read already cover OKF's list/search/read). Per-plugin choice; a "build both,
+  measure" candidate.
+- **Degree of OKF formalism** — full v0.1 conformance vs. this "OKF-compatible form." Plugins sit at
+  different points (ms-ai-architect targets the fuller package; linkedin-studio emits the minimal form
+  + extension keys; okr has writer + checker). **The minimal contract (§3) is the floor all meet;**
+  going further is per-plugin and never required by this spec.
+
+## 9. Verified premise corrections (dead-ends — do not plan against these)
+
+Ground-truth-checked against the live `GoogleCloudPlatform/knowledge-catalog` repo (research agent,
+2026-06-26, file+URL log retained). These overturn earlier framing in the per-plugin design notes:
+
+1. **`mdcode` / `kcmd` is NOT an OKF tool.** It is a Google Cloud **Dataplex** git-sync tool whose
+   on-disk markdown carries a *different* frontmatter schema (`id`/`resource.name`/`createTime`/`links`)
+   than OKF (`type`/`title`/`description`/`tags`/`timestamp`). Do **not** plan to emit or sync OKF
+   bundles via mdcode. (Corrects the "metadata as code" pattern listed in ms-ai-architect's ecosystem
+   digest.)
+2. **No reusable OKF *ingest* code exists.** The repo's `reference_agent` is a BigQuery+web → OKF
+   producer, Gemini/GCP-bound; it reads a BQ dataset + seed URLs, not a document folder. The GCP-free
+   reusable parts are the **SPEC**, the **emit/serialize/validate** core, and the **`index.md`
+   synthesis** — *patterns*, not a drop-in library. Classify/convert of arbitrary docs is 100%
+   build-yourself.
+3. **"OKF has no ingest" is true of the *format*, not the *repo*.** And the per-plugin design notes
+   never actually asked for auto-classification — all three frame the work as *OKF as the storage form
+   for a user-owned wiki* + a *retrieval skill* + a *maintenance mechanism*, with ingest being light
+   ("onboarding writes OKF-conformant").
+
+## 10. Staged plan
+
+- **Stage 1 — Shared form (this document).** Cheap, delivers interop alone. Each plugin's user-data
+  conforms; one reader traverses all three. **This alone meets the interop goal.**
+- **Stage 2 — Measure divergence.** Do the per-plugin retrieval paths diverge enough to hurt? Only a
+  *measured* "yes" justifies Stage 3 (operator anti-pattern: ambitious initiatives where a config tweak
+  suffices).
+- **Stage 3 — Conditional shared skill.** If justified: extract/generalize okr's working retrieval
+  skill into one home (§11), with a discovery convention for where each plugin's brain lives. **Do not
+  build before Stage 2 says so.**
+
+## 11. Homes
+
+- **This spec** — catalog/marketplace level (here), owned by no single plugin.
+- **A future shared skill** (Stage 3 only) — a standalone marketplace plugin (own repo, release-tagged,
+  catalog-pinned), installable alongside the others, serving the user's own context directly. Rejected
+  alternatives: duplicate-per-plugin (drift risk); user-level `~/.claude/skills/` (unversioned, outside
+  the catalog).
+
+## 12. Versioning
+
+Two independent version markers:
+
+- **`okf_version`** in each bundle-root `index.md` — the upstream Google OKF version the bundle targets
+  (currently `0.1`). When Google bumps OKF, each plugin re-checks conformance.
+- **This convention's version** (top of this file) — bumped when the shared form changes. `log.md`
+  records both. Hooks are offline (no auto-poll); version drift is caught by human review + the
+  `okf_version` echo in `okf-check`.
+
+## 13. Success criterion
+
+Measured against **user value** (does the plugin retrieve the right personal/org context in chat and
+commands?) + **maintenance reliability** — **not** against formal OKF conformance for its own sake.
+(Operator, inherited identically by all three tracks.)
+
+## 14. References
+
+- **OKF SPEC v0.1:** `github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md`
+  (12 June 2026, "a starting point, not a finished standard").
+- **Per-plugin design notes:** linkedin-studio `docs/okf-convergence-brief.md`; okr
+  `docs/okf-second-brain-note-2026-06.md`; ms-ai-architect `docs/okf-second-brain-brief-2026-06.md`.
+- **Reference checker:** okr `scripts/okf-check.mjs` (+ `okf-index.mjs`, `lib/frontmatter.mjs`).
+- **Reference design:** linkedin-studio `docs/second-brain/architecture.md`; engine `scripts/brain/`.
+- **Coordination + rollout status:** `log.md` (this directory).