create-bkn

# Create BKN

Generate well-formed BKN directories (Markdown + YAML frontmatter) per v2.0.1.

## Works with ontology-core

**create-bkn** authors the `.bkn` tree; **ontology-core** runs `ontology bkn push` / `pull` after files exist.

## What is BKN

BKN is Markdown + YAML frontmatter for schema; one file per definition under typed subfolders. Details (sections, required tables, types) live in [references/SPECIFICATION.llm.md](references/SPECIFICATION.llm.md).

## Directory layout

```
{network_dir}/
├── SKILL.md
├── network.bkn
├── CHECKSUM                 # optional; SDK may generate
├── object_types/
├── relation_types/
├── action_types/
├── concept_groups/
└── data/                    # optional CSV instance data
```

## Workflow

1. **Gather requirements** — objects, relations, actions, optional concept groups
2. **Read spec** — [references/SPECIFICATION.llm.md](references/SPECIFICATION.llm.md) (format rules, sections, frontmatter types)
3. **Pick templates** — copy/adapt from [assets/templates/](assets/templates/) (`network_type.bkn.template`, `object_type.bkn.template`, …)
4. **Create `network.bkn`** — root file; align with Network Overview
   - **MUST**: generate a fresh **UUID v4** locally (e.g. Python `uuid.uuid4()`) and write it as the `id` field in frontmatter at file creation time. Never leave `id` empty, `null`, `~`, or absent — `ontology bkn validate` / `push` both require a non-empty string id, and the bkn-creator flow does **not** call `ontology bkn create` to acquire a server-assigned id.
   - The locally generated UUID is the final `kn_id`; any other `.bkn` file that references the network id (e.g. `network_id` in `object_types/*.bkn`) must reuse the same UUID.
5. **Create `object_types/*.bkn`** — one file per object, `{id}.bkn`
6. **Create `relation_types/*.bkn`** — one file per relation
7. **Create `action_types/*.bkn`** — one file per action
8. **Create `concept_groups/*.bkn`** — optional
9. **Update `network.bkn`** — list all IDs in Network Overview
10. **Add root `SKILL.md` in the BKN directory** — same folder as `network.bkn` (this is **not** the create-bkn skill file); agent-facing guide for that network (see [Delivered BKN: root SKILL.md](#delivered-bkn-root-skillmd))
11. **Review (MUST)** — cross-check [Validation checklist](#validation-checklist) and [Business rules placement](#business-rules-placement); fix IDs, cross-refs, headings
    - 特别核对 `action_types/*.bkn` 每个文件 frontmatter 是否含 `action_type: add|modify|delete` 这一行（**位置在 frontmatter，不在 markdown body 的 Bound Object 表**），遇到查询/监控/追溯/校验等只读语义，**删掉对应 ActionType 文件并在 `network.bkn` 的 Network Overview 同步移除该 id**
12. **Validate (MUST)** — `ontology bkn validate <dir>` (see [Validation](#validation))
13. **Import** (optional) — `ontology bkn push <dir>`

## Import (ontology CLI)

**无需安装**。`ontology` 已内置在执行环境，直接调用即可。

- **BKN validation** — If workflow step 12 (`ontology bkn validate <dir>`) **already succeeded** for this directory, **do not** repeat validate before `push` unless you changed `.bkn` files. If you have **not** validated yet, run `validate` before `push`.

```bash
ontology bkn push <dir> [--branch main] [-bd <business-domain>]
```

`-bd` / `--biz-domain` is optional. If you omit it, the CLI resolves the business domain automatically.

Export: `ontology bkn pull <kn-id> [<dir>]`. More subcommands: `ontology bkn --help` (see ontology-core skill if loaded).

## Validation

`ontology bkn validate <dir>` — must pass before delivery or upload. It loads `network.bkn` and sibling `.bkn` files. Success prints counts; on failure fix `.bkn` files and re-run.

## Per-type reference

| Kind | Spec (section) | Template | Example (k8s) |
|------|------------------|----------|---------------|
| Network | `knowledge_network` in spec | [assets/templates/network_type.bkn.template](assets/templates/network_type.bkn.template) | [references/examples/k8s-network/network.bkn](references/examples/k8s-network/network.bkn) |
| Object | `object_type` | [assets/templates/object_type.bkn.template](assets/templates/object_type.bkn.template) | [references/examples/k8s-network/object_types/pod.bkn](references/examples/k8s-network/object_types/pod.bkn) |
| Relation | `relation_type` | [assets/templates/relation_type.bkn.template](assets/templates/relation_type.bkn.template) | [references/examples/k8s-network/relation_types/pod_belongs_node.bkn](references/examples/k8s-network/relation_types/pod_belongs_node.bkn) |
| Action | `action_type` | [assets/templates/action_type.bkn.template](assets/templates/action_type.bkn.template) | [references/examples/k8s-network/action_types/restart_pod.bkn](references/examples/k8s-network/action_types/restart_pod.bkn) |
| Concept group | `concept_group` | [assets/templates/concept_group.bkn.template](assets/templates/concept_group.bkn.template) | [references/examples/k8s-network/concept_groups/k8s.bkn](references/examples/k8s-network/concept_groups/k8s.bkn) |

Full rules and optional sections: [references/SPECIFICATION.llm.md](references/SPECIFICATION.llm.md).

## Naming conventions

- **ID**: lowercase, digits, underscores; **file**: `{id}.bkn` under the matching folder
- **Headings**: `#` network title, `##` type block, `###` section, `####` logic property
- **Frontmatter**: at least `type`, `id`, `name` (see spec for each type)

## Business rules placement

Rules must sit in spec-defined places so import persists them. Full wording: [references/SPECIFICATION.llm.md](references/SPECIFICATION.llm.md#输出规则).

- **Network-level** — prose in `network.bkn` right after `# {title}` (before structured sections like `## Network Overview`)
- **Type-level** — prose in each type file after `## ObjectType:` / `## RelationType:` / … and **before** the first `###`; never in frontmatter
- **Property-level** — in **Data Properties** table **Description** column
- **No extra sections** — do not add Markdown outside the standard sections; parsers may drop unparsed content on import

## Validation checklist

- [ ] `net