GoogleCloudPlatform / GoogleCloudPlatform/knowledge-catalog

okf: offer five small-business sample bundles (trades, v0.2)

Open
#282 1 comment 0 reactions 0 assignees View on GitHub
Dominant language
TypeScript
Stars
9.2k
Forks
782
Avg merge
6h 36m
Merged PRs (30d)
85

Description

## What

Offering five small-business OKF **v0.2** sample bundles, one per trade: decorator, plumber, electrician, roofer, builder. Happy to send them as a PR under `okf/bundles/` in whatever shape you prefer, or to leave them where they are if they're not a fit.

They live at [muhaj/okf-job-sheet → `bundles/`](https://github.com/muhaj/okf-job-sheet/tree/main/bundles) today.

## Why these might be useful

The four bundles in the repo (GA4, Stack Overflow, Bitcoin, Acme Retail) are all data-warehouse shaped - tables, columns, metrics, foreign keys. That's the primary use case and they model it well.

These are the other shape: a single small business, where the knowledge is operational rather than relational. What it charges, where it works, what it refuses, and the point at which an agent should stop talking and fetch a human. The v0.2 post asked for sample bundles, and this seemed different enough to be worth offering rather than another schema.

They also exercise parts of v0.2 the current samples don't lean on much - `verified` on every concept, `stale_after`, and an **Attested Computation** with its attester.

## Contents

Each bundle is 21 files: 20 `.md` plus one attester `.js`.

- `business/` - Business Identity, Credential Set, Service Area
- `services/` - Service Catalogue, Exclusion List
- `pricing/` - Rate Card, Commercial Terms, Pricing Method
- `computations/` - one **Attested Computation** (the quote formula), with `/attesters/estimate_equality.js`
- `operations/` - Availability, Access Constraints, Escalation Policy
- `intake/` - Intake Questionnaire
- `index.md` at the root and in each subdirectory, plus `log.md`

13 concepts per bundle, 13 concept types, one of each.

## Conformance

Checked mechanically across all five, not by eye:

- Every non-reserved `.md` has parseable YAML frontmatter with a non-empty `type` (section 9)
- `index.md` and `log.md` carry no frontmatter and follow their structures (section 66, section 5.2)
- 13 absolute bundle-relative links per bundle, **0 dangling** (section 5.1)
- `okf_version` appears in exactly one file
- All 13 concepts carry a `verified` entry with a `human:` actor - these are signed off, unlike the tool's default output, which is honestly marked unverified when nobody ticked the box
- No `timestamp` key and no `# Citations` heading anywhere (the two v0.1 → v0.2 renames)

## Provenance

They're generated from the tool's own presets by [`scripts/build-bundles.mjs`](https://github.com/muhaj/okf-job-sheet/blob/main/scripts/build-bundles.mjs) rather than hand-written, so they can't drift from what the generator emits. There's also a tamper drill in CI that runs each bundle's Attested Computation through a verifier and asserts it rejects a swapped constant, an added term, a dropped `max()` and a mutated result.

**Disclosure:** I wrote the tool that produces them. The businesses are realistic rather than real - one is my own decorating firm's actual rate card, the other four are representative for their trade.

Related: I mentioned these briefly in #167 but they're not a tools-list item, hence the separate issue.

Contributor guide

Open the contributing guide

Research direction

Start by reading okf/bundles/ and the existing four sample bundles, then inspect scripts/build-bundles.mjs and the CI tamper drill mentioned in the issue. Done means maintainers accept the five bundles in the repository with the stated frontmatter, links, version, verification, and attestation checks passing.

Written by the indexing model from the issue text.

Assessment

Tech stack
javascript
Domain
content
Issue type
Feature
Difficulty
3/5
Estimated time
1-2 days
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
52/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.