okf 1.0.0

data/lib/okf/skill/reference/SPEC.md

@@ -0,0 +1,460 @@
+<!--
+  Vendored from the Open Knowledge Format reference repository.
+  Source:  https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md
+  Commit:  ee67a5ca27044ebe7c38385f5b6cffc2305a9c1a
+  License: Apache-2.0 (c) Google LLC — included verbatim under its terms.
+           Full license text: ./APACHE-2.0.txt
+  This is the canonical normative reference loaded by the okf skill.
+-->
+
+# Open Knowledge Format (OKF)
+
+**Version 0.1 — Draft**
+
+OKF is an open, human- and agent-friendly format for representing
+*knowledge* — the metadata, context, and curated insight that surrounds
+data and systems. It is designed to be authored by people, generated by
+agents, exchanged across organizations, and consumed by both.
+
+The format is intentionally minimal: a directory of markdown files with
+YAML frontmatter. There is no schema registry, no central authority, and
+no required tooling. If you can `cat` a file, you can read OKF; if you
+can `git clone` a repo, you can ship it.
+
+---
+
+## 1. Motivation
+
+The space of knowledge representation for AI agents is evolving quickly,
+and many incompatible conventions are emerging. OKF takes the position
+that knowledge is best represented in commonly accessible, established
+formats that are:
+
+- **Readable** by humans without tooling.
+- **Parseable** by agents without bespoke SDKs.
+- **Diffable** in version control.
+- **Portable** across tools, organizations, and time.
+
+The format is minimally opinionated. It standardizes only the small set
+of structural conventions needed to make a knowledge corpus
+*self-describing* — anything beyond that is left to the producer.
+
+### Goals
+
+1. Define a universal format that **enrichment agents** can write into.
+2. Inform how **consumption agents** should read and traverse it.
+3. Facilitate **exchange** of knowledge across systems and organizations.
+4. Standardize the small number of **required** fields that must be
+   present for content to be meaningfully consumed.
+
+### Non-goals
+
+- Defining a fixed taxonomy of concept types.
+- Prescribing storage, serving, or query infrastructure.
+- Replacing domain-specific schemas (Avro, Protobuf, OpenAPI, etc.) —
+  OKF *references* them; it does not subsume them.
+
+---
+
+## 2. Terminology
+
+- **Knowledge Bundle** — A self-contained, hierarchical collection of
+  knowledge documents. The unit of distribution.
+- **Concept** — A single unit of knowledge within a bundle. Represented
+  as one markdown document. May describe a tangible asset (a table, an
+  API), an abstract idea (a metric, a business process), or anything in
+  between.
+- **Concept ID** — The path of the concept's file within the bundle,
+  with the `.md` suffix removed. For example, `tables/users.md` has
+  concept ID `tables/users`.
+- **Frontmatter** — YAML metadata block delimited by `---` at the top of
+  a markdown file.
+- **Body** — Everything in the file after the frontmatter.
+- **Link** — A standard markdown link from one concept to another, used
+  to express relationships beyond the implicit parent/child hierarchy.
+- **Citation** — A link from a concept to an external source that
+  supports a claim in the body.
+
+---
+
+## 3. Bundle Structure
+
+A bundle is a directory tree of markdown files. The directory structure
+is independent of the domain — producers organize concepts however makes
+sense for the knowledge being captured.
+
+```
+path/to/bundle/
+├── index.md                      # Optional. Directory listing for progressive disclosure.
+├── log.md                        # Optional. Chronological history of updates.
+├── <concept>.md                  # A concept at the bundle root.
+└── <subdirectory>/               # Subdirectories organize concepts into groups.
+    ├── index.md
+    ├── <concept>.md
+    └── <subdirectory>/
+        └── …
+```
+
+A bundle MAY be distributed as:
+
+- A git repository (recommended — provides history, attribution, diffs).
+- A tarball or zip archive of the directory.
+- A subdirectory within a larger repository.
+
+### 3.1 Reserved filenames
+
+The following filenames have defined meaning at any level of the
+hierarchy and MUST NOT be used for concept documents:
+
+| Filename     | Purpose                                                |
+|--------------|--------------------------------------------------------|
+| `index.md`   | Directory listing. See §6.                             |
+| `log.md`     | Update history. See §7.                                |
+
+All other `.md` files are concept documents.
+
+Tags themselves remain a first-class concept — see the `tags`
+frontmatter field in §4.1. OKF does not specify a separate file format
+for aggregating documents by tag; producers that want a tag-browsing
+view can synthesize one at consumption time by scanning frontmatter.
+
+---
+
+## 4. Concept Documents
+
+Every concept is a UTF-8 markdown file. It has two parts:
+
+1. A **YAML frontmatter block**, delimited by `---` on its own line at
+   the start of the file and a closing `---` on its own line.
+2. A **markdown body**, containing free-form content.
+
+### 4.1 Frontmatter
+
+```yaml
+---
+type: <Type name>                  # REQUIRED
+title: <Optional display name>
+description: <Optional one-line summary>
+resource: <Optional canonical URI for the underlying asset>
+tags: [<tag>, <tag>, …]            # Optional
+timestamp: <ISO 8601 datetime>     # Optional last-modified time
+# … other producer-defined key/value pairs
+---
+```
+
+**Required:**
+
+- `type` — A short string identifying the kind of concept. Consumers
+  use this for routing, filtering, and presentation. Example values:
+  `BigQuery Table`, `BigQuery Dataset`, `API Endpoint`, `Metric`,
+  `Playbook`, `Reference`.
+
+  Type values are **not** registered centrally. Producers SHOULD pick
+  values that are descriptive and self-explanatory; consumers MUST
+  tolerate unknown types gracefully (typically by treating them as
+  generic concepts).
+
+**Recommended (in priority order):**
+
+- `title` — Human-readable display name. If omitted, consumers MAY
+  derive a title from the filename.
+- `description` — A single sentence summarizing the concept. Used by
+  `index.md` generators, search snippets, and previews.
+- `resource` — A URI that uniquely identifies the underlying asset the
+  concept describes. Absent for concepts that describe abstract ideas
+  rather than physical resources.
+- `tags` — A YAML list of short strings for cross-cutting categorization.
+- `timestamp` — ISO 8601 datetime of last meaningful change.
+
+**Extensions:** Producers MAY include any additional keys. Consumers
+SHOULD preserve unknown keys when round-tripping and SHOULD NOT reject
+documents with unrecognized fields.
+
+### 4.2 Body
+
+The body is standard markdown. Producers SHOULD favor structural
+markdown — headings, lists, tables, fenced code blocks — over freeform
+prose, since structure aids both human reading and agent retrieval.
+
+There are no required body sections. The following section headings have
+**conventional** meaning and SHOULD be used when applicable:
+
+| Heading        | Purpose                                                |
+|----------------|--------------------------------------------------------|
+| `# Schema`     | Structured description of an asset's columns/fields.   |
+| `# Examples`   | Concrete usage examples, often as fenced code blocks.  |
+| `# Citations`  | External sources backing claims in the body. See §8.   |
+
+### 4.3 Example: a concept bound to a resource
+
+```markdown
+---
+type: BigQuery Table
+title: Customer Orders
+description: One row per completed customer order across all channels.
+resource: https://console.cloud.google.com/bigquery?p=acme&d=sales&t=orders
+tags: [sales, orders, revenue]
+timestamp: 2026-05-28T14:30:00Z
+---
+
+# Schema
+
+| Column        | Type      | Description                              |
+|---------------|-----------|------------------------------------------|
+| `order_id`    | STRING    | Globally unique order identifier.        |
+| `customer_id` | STRING    | Foreign key into [customers](/tables/customers.md). |
+| `total_usd`   | NUMERIC   | Order total in US dollars.               |
+| `placed_at`   | TIMESTAMP | When the customer submitted the order.   |
+
+# Joins
+
+Joined with [customers](/tables/customers.md) on `customer_id`.
+
+# Citations
+
+[1] [BigQuery table schema](https://console.cloud.google.com/bigquery?p=acme&d=sales&t=orders)
+```
+
+### 4.4 Example: a concept not bound to a resource
+
+```markdown
+---
+type: Playbook
+title: Incident response — data freshness alert
+description: Steps to triage a freshness alert on the orders pipeline.
+tags: [oncall, incident]
+timestamp: 2026-04-12T09:00:00Z
+---
+
+# Trigger
+
+A freshness alert fires when `orders` lags more than 30 minutes behind
+its expected SLA. See the [orders table](/tables/orders.md).
+
+# Steps
+
+1. Check the [ingestion job dashboard](https://example.com/dash).
+2. …
+```
+
+---
+
+## 5. Cross-linking
+
+Concepts MAY link to other concepts using standard markdown links. Two
+forms are supported:
+
+### 5.1 Absolute (bundle-relative) links
+
+Begin with `/`, interpreted relative to the bundle root.
+
+```markdown
+See the [customers table](/tables/customers.md) for the join key.
+```
+
+This is the **recommended** form because it is stable when documents are
+moved within their subdirectory.
+
+### 5.2 Relative links
+
+Standard markdown relative paths.
+
+```markdown
+See the [neighboring concept](./other.md).
+```
+
+### 5.3 Link semantics
+
+A link from concept A to concept B asserts a *relationship*. The
+specific kind of relationship (parent/child, references, joins-with,
+depends-on, etc.) is conveyed by the surrounding prose, not by the link
+itself. Consumers that build a graph view typically treat all links as
+directed edges of an untyped relationship.
+
+Consumers MUST tolerate broken links — a link whose target does not
+exist in the bundle is not malformed; it may simply represent
+not-yet-written knowledge.
+
+---
+
+## 6. Index Files
+
+An `index.md` file MAY appear in any directory, including the bundle
+root. It enumerates the directory's contents to support **progressive
+disclosure** — letting a human or agent see what is available before
+opening individual documents.
+
+Index files contain no frontmatter. The body uses one or more sections,
+each grouping concepts under a heading:
+
+```markdown
+# Section / Group Heading
+
+* [Title 1](relative-url-1) - short description of item 1
+* [Title 2](relative-url-2) - short description of item 2
+
+# Another Section
+
+* [Subdirectory](subdir/) - short description of the subdirectory
+```
+
+Entries SHOULD include the description from the linked concept's
+frontmatter. Producers MAY generate `index.md` automatically; consumers
+MAY synthesize one on the fly when none is present.
+
+---
+
+## 7. Log Files (optional)
+
+A `log.md` file MAY appear at any level of the hierarchy to record the
+history of changes to that scope. The format is a flat list of
+date-grouped entries, newest first:
+
+```markdown
+# Directory Update Log
+
+## 2026-05-22
+* **Update**: Added new BigQuery table reference for [Customer Metrics](/tables/customer-metrics.md).
+* **Creation**: Established the [Dataplex Playbook](/playbooks/dataplex.md).
+
+## 2026-05-15
+* **Initialization**: Created foundational directory structure.
+* **Update**: Added progressive-disclosure guidelines to the root [index](/index.md).
+```
+
+Date headings MUST use ISO 8601 `YYYY-MM-DD` form. Log entries are
+prose; the leading bold word (`**Update**`, `**Creation**`,
+`**Deprecation**`, etc.) is a convention, not a requirement.
+
+---
+
+## 8. Citations
+
+When a concept's body makes claims sourced from external material,
+those sources SHOULD be listed under a `# Citations` heading at the
+bottom of the document, numbered:
+
+```markdown
+# Citations
+
+[1] [BigQuery public dataset announcement](https://cloud.google.com/blog/products/data-analytics/...)
+[2] [Internal data quality runbook](https://wiki.acme.internal/data/quality)
+```
+
+Citation links MAY be absolute URLs, bundle-relative paths, or paths
+into a `references/` subdirectory that mirrors external material as
+first-class OKF concepts.
+
+---
+
+## 9. Conformance
+
+A bundle is **conformant** with OKF v0.1 if:
+
+1. Every non-reserved `.md` file in the tree contains a parseable YAML
+   frontmatter block.
+2. Every frontmatter block contains a non-empty `type` field.
+3. Every reserved filename (`index.md`, `log.md`) follows the structure
+   described in §6 and §7 respectively when present.
+
+Consumers SHOULD treat all other constraints as soft guidance. In
+particular, consumers MUST NOT reject a bundle because of:
+
+- Missing optional frontmatter fields.
+- Unknown `type` values.
+- Unknown additional frontmatter keys.
+- Broken cross-links.
+- Missing `index.md` files.
+
+This permissive consumption model is intentional: OKF is meant to
+remain useful as bundles grow, get refactored, and are partially
+generated by agents.
+
+---
+
+## 10. Relationship to other formats
+
+OKF is intentionally close to several established patterns:
+
+- **LLM "wiki" repositories** that use markdown + frontmatter as
+  agent-readable knowledge bases.
+- **Personal knowledge tools** like Obsidian and Notion, which use
+  hierarchical markdown with cross-links.
+- **"Metadata as code"** approaches that store catalog metadata
+  alongside source code rather than in a separate registry.
+
+OKF differs primarily in being **specified** — pinning down the small
+set of rules needed for interoperability without dictating tooling.
+
+---
+
+## 11. Versioning
+
+This document specifies OKF version **0.1**. Future revisions will be
+versioned in the form `<major>.<minor>`:
+
+- A **minor** version bump introduces backward-compatible additions
+  (new optional fields, new conventional section headings).
+- A **major** version bump may make breaking changes (renaming required
+  fields, changing reserved filenames).
+
+Bundles MAY declare the OKF version they target by including
+`okf_version: "0.1"` in a bundle-root `index.md` frontmatter block (the
+only place frontmatter is permitted in an `index.md`). Consumers that
+do not understand the declared version SHOULD attempt best-effort
+consumption rather than refusing the bundle.
+
+---
+
+## Appendix A — Minimal example bundle
+
+```
+my_bundle/
+├── index.md
+├── datasets/
+│   ├── index.md
+│   └── sales.md
+└── tables/
+    ├── index.md
+    ├── orders.md
+    └── customers.md
+```
+
+`datasets/sales.md`:
+
+```markdown
+---
+type: BigQuery Dataset
+title: Sales
+description: All sales-related tables for the retail business.
+resource: https://console.cloud.google.com/bigquery?p=acme&d=sales
+tags: [sales]
+timestamp: 2026-05-28T00:00:00Z
+---
+
+The sales dataset contains transactional tables, including
+[orders](/tables/orders.md) and [customers](/tables/customers.md).
+```
+
+`tables/orders.md`:
+
+```markdown
+---
+type: BigQuery Table
+title: Orders
+description: One row per completed customer order.
+resource: https://console.cloud.google.com/bigquery?p=acme&d=sales&t=orders
+tags: [sales, orders]
+timestamp: 2026-05-28T00:00:00Z
+---
+
+# Schema
+
+| Column        | Type      | Description                  |
+|---------------|-----------|------------------------------|
+| `order_id`    | STRING    | Unique order identifier.     |
+| `customer_id` | STRING    | FK to [customers](/tables/customers.md). |
+| `total_usd`   | NUMERIC   | Order total in USD.          |
+
+Part of the [sales dataset](/datasets/sales.md).
+```

data/lib/okf/skill/reference/authoring.md

@@ -0,0 +1,218 @@
+# Authoring OKF well — the craft
+
+The spec ([SPEC.md](SPEC.md)) tells you what is *legal*. This file is what is
+*good* — the modelling judgment that turns a pile of conformant files into
+knowledge worth consuming. Read it before `produce` or `maintain`, and keep the §9
+conformance rules in mind (parseable frontmatter, a non-empty `type`, and
+well-formed reserved files — the hard rules in [SKILL.md](../SKILL.md)); everything
+else is guidance a consumer must tolerate.
+
+## What each SPEC section governs
+
+Consult the right section on demand instead of re-reading all of [SPEC.md](SPEC.md):
+
+| § | Governs | Reach for it when |
+|---|---------|-------------------|
+| §3 | bundle structure, reserved filenames | laying out directories |
+| §4 | concept documents & frontmatter | writing or validating a concept |
+| §5 / §5.3 | cross-links; **broken links are tolerated** | linking; judging a "broken" link |
+| §6 | index files & progressive disclosure | orienting; writing or synthesizing an index |
+| §7 | log files | recording history |
+| §8 | citations & provenance | any external or empirical claim |
+| §9 | conformance — the hard gate | what `validate` may and may not reject |
+| §11 | versioning (`okf_version`) | the root index's one allowed field |
+
+## Modelling principles
+
+These are the decisions that make or break a bundle. None are enforced by the
+tools — they are yours to get right.
+
+### One concept = one file — but what is a concept?
+A concept is the smallest unit of knowledge someone would want to **link to or
+cite on its own**. If two things are always referenced together, they are one
+concept; if either is referenced alone, split them. Err atomic — it is cheap to
+link two files and expensive to untangle one that grew two identities. Signs a
+file should split: two `type`s fighting for the frontmatter, two audiences, or a
+heading that others would plausibly link to directly. The file path (minus `.md`)
+is the concept's stable ID, so name it for what it *is*, not where it sits today.
+
+### `type` is the graph's vocabulary
+`type` is the only required field, and it is the dimension every consumer groups
+and colours by (the graph server colours nodes by it; graph analysis clusters by
+it). It is freeform — the spec does not enumerate types — and that freedom is a
+responsibility. Keep a **small, consistent, descriptive** vocabulary per bundle
+(`Service`, `Dataset`, `Metric`, `Decision`, `Playbook`, `Runbook`, …). Reusing
+types across files is what makes the graph legible; inventing a new type per file
+makes `type` meaningless. Before adding a new type, check what the bundle already
+uses.
+
+### Tags are the connective axis — curate them like a vocabulary
+`type` says what a concept *is*; the directory says where it *lives*; `tags` are
+the only axis that cuts across both. A tag earns its place one of two ways: by
+**connecting** concepts that type and area don't already group (a `billing` tag
+spanning a service, a dataset, and a decision), or by **marking** something worth
+flagging even on one concept (`security`, `deprecated`). A tag that merely
+restates the concept's own type, area, or title adds no edge — it is noise wearing
+a tag's clothes. Reuse before minting: run `okf tags <dir>` and pick from the
+existing vocabulary first; 2–4 tags per concept is plenty. Scattered singletons
+are how a vocabulary rots into one label per file.
+
+### Topology: organize by domain, not by type
+Lay out directories by what the knowledge is *about* (`services/`, `datasets/`,
+`decisions/`), not by concept type. The directory tree is itself knowledge — it
+shows a reader how the system decomposes, and it usually mirrors the shape of the
+codebase or the org. A `types/`-first layout scatters related concepts and buries
+the domain.
+
+### `resource` is the bridge to reality
+Set `resource` (a canonical URI) **only** when a concept *is* a real, addressable
+asset — a table (`bigquery://…`), a service repo, a dashboard, an endpoint. Its
+presence is what lets `maintain` find every concept affected by a changed asset by
+grepping for that URI. Abstract concepts — a decision, a principle, a metric
+definition — have no resource, and **omitting it is meaningful**, not laziness. Do
+not invent placeholder URIs.
+
+### Links are untyped on purpose
+A markdown link asserts only "these two relate." The *kind* of relationship —
+depends-on, supersedes, derived-from, owns — lives in the **prose around the
+link**, never in a made-up typed-edge syntax. Write the sentence that explains the
+relationship and put the link inside it. Prefer absolute bundle-relative targets
+(`/services/auth-api.md`) so links survive file moves. A link to a concept that
+does not exist yet is fine — it is not-yet-written knowledge (§5.3), and `lint`'s
+backlog will surface it as demand.
+
+### Provenance is what makes knowledge trustworthy (§8)
+Any external or empirical claim — a latency number, an approval, a quota, a
+"because X team decided Y" — should carry a citation to its source under a
+`# Citations` heading. Uncited claims are exactly how a bundle decays into folklore
+nobody trusts. `lint`'s provenance category exists to catch missing and broken
+citations; write them as you go so you never have to reconstruct them.
+
+### Capture the non-obvious — not what code already says
+A bundle that restates function signatures or config keys goes stale the moment
+the code changes and adds no knowledge. Capture what you **cannot** derive by
+reading one source file: the *why* behind a design, cross-cutting relationships,
+decisions and their tradeoffs, operational tribal knowledge, the metric that
+actually matters. If the code or git history already records it faithfully, link
+to it rather than duplicating it.
+
+### Write for both readers at once
+Use structural markdown so an agent can extract deterministically and a human can
+skim: headings, tables, fenced code, lists. Conventional headings a reader expects
+are `# Schema` (field/column tables), `# Examples`, and `# Citations`. Fill
+recommended frontmatter — `title`, `description`, `tags`, `timestamp` (ISO 8601) —
+whenever it aids consumption.
+
+### Reserved files
+`index.md` is a directory listing and carries **no frontmatter** — with one
+exception: the **bundle-root** `index.md` is the only index that may carry
+frontmatter, and it may carry *only* `okf_version: "0.1"` (§11; `validate` §9.3
+flags any other key there). `log.md` is an ISO-dated change history, newest first.
+Never use these names for concepts. Templates:
+[concept](../templates/concept.md), nested [index](../templates/index.md),
+bundle-root [root-index](../templates/root-index.md), [log](../templates/log.md).
+
+## Playbooks
+
+### produce — create or extend a bundle
+1. Read [SPEC.md](SPEC.md) if you are unsure of any rule.
+2. Pick the source(s): **code** (derive concepts from source, READMEs, docstrings,
+   config), **docs/wiki** (distill pages into concepts; cite the originals under
+   `# Citations`), **manual** (decisions, playbooks, metrics that live only in
+   people's heads).
+3. Choose a domain-based directory layout. One concept per file.
+4. Write each concept from [templates/concept.md](../templates/concept.md): a
+   descriptive `type` from the bundle's vocabulary, recommended fields filled,
+   cross-links to related concepts written into prose.
+5. Add or refresh `index.md` per directory from
+   [templates/index.md](../templates/index.md); for the bundle root use
+   [templates/root-index.md](../templates/root-index.md) so it carries
+   `okf_version: "0.1"`. Append a dated entry to `log.md`.
+6. **Close out** — walk the Closeout gate below (`validate` + `lint` are part of it,
+   see [cli.md](cli.md)) before finishing.
+
+### maintain — keep a bundle in sync with reality
+1. **Orient before hunting.** Run `okf index <dir>` (the §6 map — every directory's
+   index body, rollups, and listings), read `log.md` (the §7 baseline: what changed
+   last), and `okf stats <dir>` (size and shape) *before* you grep. It is the
+   cheapest context and it primes the hunt — and it is the only reliable way to
+   catch enumeration drift, because **grep cannot find an index entry that is
+   missing.** (This is the always-on reflex in [SKILL.md](../SKILL.md).)
+2. **Find *every* affected concept** — the failure mode is fixing only the obvious
+   one. Don't rely on reading the whole bundle; that only scales on tiny ones. Grep
+   the changed asset's `resource` URI across the bundle, grep its path/name, and use
+   `okf graph --json` to pull the concepts that link *to* the ones you're touching.
+   Let grep and the graph find them so nothing drifts silently.
+3. Update bodies and `timestamp`; fix or add cross-links; create new concepts for
+   new assets; mark retired assets with a `**Deprecation**` note rather than
+   silently deleting the context that explains them.
+4. **Update every enumeration that names what you changed — including `index.md`
+   bodies**, not just the concept files: a new, renamed, or removed concept changes
+   its directory's index listing too. Append a dated `log.md` entry. Step 1's map
+   is how you verify this — re-run `okf index` and confirm each listing matches
+   reality.
+5. Run `validate`, then `lint` to catch the curation drift the change introduced —
+   new orphans, broken citations, dangling index entries. Add `--stale-after`
+   (e.g. `90d`) if concepts carry timestamps: freshness is off by default, so a
+   plain `lint` will not tell you what the change left stale.
+6. **Review loose files** — run `okf loose <dir>` (the folder-grouped view of
+   `lint`'s `unlinked` check): the concepts with **no cross-links in or out**, which
+   float in the graph. This is a semantic pass the tool cannot do for you — for each
+   floater, judge intent:
+   - **should it link out?** the concept relates to others but says so nowhere —
+     write the sentence that explains the relationship and put the link in it;
+   - **should something link to it?** it is knowledge others should reach by
+     following links, not just via an index — add the inbound link from where it
+     belongs;
+   - **legitimately terminal?** a backlog item, a spec reference, a leaf reachable
+     by design only through its index — leave it. **Terminal-by-design is not a
+     defect.** Loose ≠ orphan: an index listing makes a file *reachable* (not an
+     orphan) but is not a graph edge, so an indexed file can still float here.
+7. **Curate the tag vocabulary** when the pass touched tags, or when `okf tags
+   <dir>` shows a long tail of singletons. Run `okf tags <dir> --by area` and
+   `--by type` — the grouped view is the analysis; read each group top-down:
+   - **twins** — two tags riding the exact same concepts (equal counts sort them
+     adjacent). Merge into one unless each genuinely names a different theme.
+   - **group-name echoes** — a tag matching its own group's name (a `format` tag
+     inside `format/`, an `overview` tag on an Overview). It restates an axis the
+     concept already carries; drop it from those concepts.
+   - **singletons** — for each, ask: would an existing tag serve? is it an
+     anticipated cluster that concepts landing soon will join? is it a deliberate
+     marker (`security`, `deprecated`)? Merge, keep, or drop accordingly — a
+     count of 1 is a question, never a verdict.
+   - **connective tags** — recurring across groups: these are the vocabulary's
+     spine. Protect them; prefer merging others *into* them over renaming them,
+     because consumers learn these keys and stability is part of their value.
+   The trap in this pass is optimizing the numbers instead of the vocabulary:
+   you can reach zero singletons by deleting every tag, and perfect cohesion by
+   tagging everything alike. The goal is a small set of tags where each one
+   either connects or marks — judged, not counted.
+
+### consume — use a bundle as context
+1. **Orient first** (the [SKILL.md](../SKILL.md) reflex): `okf index <dir>` maps the
+   whole bundle in one pass — every directory's index body, rollups, and listings —
+   and `log.md` gives recent history. Then follow links only into the concepts the
+   task needs. For a large bundle, `okf graph --json` gives the whole link structure
+   at once so you can plan a traversal without opening every file.
+2. Treat broken links as not-yet-written knowledge, not errors.
+3. **Write-back reflex:** if you learn something durable while working — a fact the
+   bundle lacks, a link it is missing, a concept that no longer matches reality —
+   switch to `maintain` and record it. That reflex is what keeps the bundle alive.
+
+## Closeout — the finishing gate
+
+`produce` step 6 and `maintain` steps 4–7 both land here: before calling an
+authoring task done, walk this once. It is the repo's "turn every task into a check
+that can fail" discipline, and followed literally it catches the enumeration drift
+grep can't:
+
+- **Index enumerations** — every `index.md` that lists what you added, renamed, or
+  removed is updated; re-run `okf index` and eyeball each listing against reality.
+  Easy to skip, expensive to miss — this is the check that was missing.
+- **`log.md`** — a dated entry, newest first.
+- **Timestamps** bumped on the concepts you touched.
+- **`validate`** — zero §9 errors.
+- **`lint`** — cheap findings cleared; pass `--stale-after` when concepts carry
+  timestamps (freshness is off by default).
+- **`loose` review + tag curation** — the two semantic passes (maintain steps 6–7);
+  worth a pass in `produce` too on a non-trivial bundle.