okf-cli 0.4.1__tar.gz → 0.4.5__tar.gz

okf_cli-0.4.5/.last-update.json

@@ -0,0 +1 @@
+{"head": "a841967e2873ae08f6af8976cc96d30cd90857c4", "timestamp": "2026-07-13T17:04:00+05:30", "mode": "update"}

{okf_cli-0.4.1 → okf_cli-0.4.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: okf-cli
-Version: 0.4.1
+Version: 0.4.5
 Summary: Open Knowledge Format tooling
 License: MIT License
         

{okf_cli-0.4.1 → okf_cli-0.4.5}/openwiki/architecture.md

@@ -48,7 +48,7 @@ Source: `src/okf/commands/list.py`, `src/okf/commands/show.py`.
 
 - Reserved name handling differs by phase:
   - Bundling phase skips `index.md`, `log.md`, `README.md` (`RESERVED`).
-  - Spec-conformance phase reserves only `index.md`, `log.md` (`SPEC_RESERVED`).
+  - Spec-conformance phase reserves `index.md`, `log.md`, `agents.md` (`SPEC_RESERVED`). `agents.md` is reserved but skipped during conformance checks (not an error).
 - Non-UTF-8 markdown is a conformance error.
 - `type` frontmatter is required and must be non-empty for non-reserved concept files.
 

{okf_cli-0.4.1 → okf_cli-0.4.5}/openwiki/domain-model.md

@@ -34,9 +34,9 @@ Implementation: `src/okf/commands/list.py`, `src/okf/commands/show.py`.
 Two rule sets:
 
 - Bundling input skip set: `index.md`, `log.md`, `README.md` (`RESERVED`)
-- Spec reserved set: `index.md`, `log.md` (`SPEC_RESERVED`)
+- Spec reserved set: `index.md`, `log.md`, `agents.md` (`SPEC_RESERVED`)
 
-Why dual sets: raw input dirs often include README-like repo artifacts; spec-level bundle reading should only reserve spec names.
+Why dual sets: raw input dirs often include README-like repo artifacts; spec-level bundle reading should only reserve spec names plus `agents.md` (generated at bundle root, never a concept).
 
 Implementation: `src/okf/core.py` + command logic.
 
@@ -99,6 +99,7 @@ Source: `src/okf/commands/bundle.py`.
 
 1. non-reserved markdown must have parseable YAML frontmatter;
 1. non-reserved markdown must include non-empty string `type`;
+1. `agents.md` is skipped entirely (no frontmatter/validation);
 1. `index.md` and `log.md` structure rules:
    - non-root `index.md` must not have frontmatter;
    - root `index.md` may have frontmatter only containing `okf_version`;

{okf_cli-0.4.1 → okf_cli-0.4.5}/openwiki/operations.md

@@ -28,8 +28,8 @@ uvx ruff format .
 For bundle smoke:
 
 ```bash
-uv run okf bundle example bundled --default-type reference --force
-uv run okf validate bundled
+uv run okf bundle example --default-type reference --force
+uv run okf validate example_knowledge_base
 ```
 
 ## CI/CD
@@ -48,8 +48,7 @@ No deploy pipeline in repo; CI currently focused on correctness tests.
 ## Repo artifacts and hygiene
 
 - `example/` contains sample source markdown.
-- `bundled-smoke/` contains generated sample output used for smoke/reference.
-- `bundled/` is git-ignored local artifact (`.gitignore`).
+- Default output (`<input>_knowledge_base`) is git-ignored local artifact (`.gitignore`).
 
 When changing command behavior, update sample docs/output only if behavior change is intentional and tested.
 

{okf_cli-0.4.1 → okf_cli-0.4.5}/openwiki/quickstart.md

@@ -11,11 +11,11 @@
 ```bash
 uv sync
 uv run okf --help
-uv run okf bundle example bundled --default-type reference --force
-uv run okf validate bundled
-uv run okf list bundled
-uv run okf show bundled tables/customers
-uv run okf bundle example bundled --default-type reference --force --strict-links
+uv run okf bundle example --default-type reference --force
+uv run okf validate example_knowledge_base
+uv run okf list example_knowledge_base
+uv run okf show example_knowledge_base tables/customers
+uv run okf bundle example --default-type reference --force --strict-links
 ```
 
 Why this sequence:

{okf_cli-0.4.1 → okf_cli-0.4.5}/openwiki/testing.md

@@ -6,6 +6,7 @@
   - parsing helpers (`parse_md`, `parse_frontmatter`)
   - frontmatter generation (`build_frontmatter`)
   - conformance engine (`check_conformance`)
+- End-to-end smoke tests: `tests/e2e/test_e2e.py` (every CLI feature)
 - CLI integration tests:
   - bundling: `tests/cli/test_bundle.py`
   - list: `tests/cli/test_list.py`

{okf_cli-0.4.1 → okf_cli-0.4.5}/openwiki/workflows.md

@@ -19,13 +19,14 @@ Lenient fallback exists for imperfect files, but strict shape gives better metad
 ### 2) Bundle to OKF
 
 ```bash
-uv run okf bundle <input-dir> <output-dir> --default-type reference --force
-uv run okf bundle <input-dir> <output-dir> --default-type reference --force --strict-links
+uv run okf bundle <input-dir> [output-dir] [--default-type <type>] [--force] [--strict-links]
+# output-dir defaults to <input-dir>_knowledge_base
+# --default-type defaults to input directory name
 ```
 
 Important behavior:
 
-- Root-level markdown requires `--default-type`, else skipped with warning.
+- Root-level markdown uses input directory name as type if `--default-type` not specified.
 - Reserved filenames skipped during bundling (`index.md`, `log.md`, `README.md`).
 - `.okfignore` in input root can skip exact bundle-relative paths.
 - `--strict-links` fails if any local `.md` link is missing or points outside bundle.
@@ -91,14 +92,13 @@ Common pitfalls:
 Repo contains:
 
 - source sample: `example/`
-- generated sample: `bundled-smoke/`
 
 Use to verify end-to-end behavior quickly:
 
 ```bash
-uv run okf bundle example bundled-smoke --default-type reference --force
-uv run okf validate bundled-smoke
-uv run okf list bundled-smoke
+uv run okf bundle example --default-type reference --force
+uv run okf validate example_knowledge_base
+uv run okf list example_knowledge_base
 ```
 
-(Generated output directory is ignored by git for default `bundled/`; see `.gitignore`.)
+(Generated output directory is ignored by git for default `example_knowledge_base/`; see `.gitignore`.)

{okf_cli-0.4.1 → okf_cli-0.4.5}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "okf-cli"
-version = "0.4.1"
+version = "0.4.5"
 description = "Open Knowledge Format tooling"
 readme = "README.md"
 license = { file = "LICENSE" }

okf_cli-0.4.5/skills/writing-knowledge-base/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: writing-knowledge-base
+description: Turn user provided content on any topic into a plain Markdown knowledge base. Invoked as /writing-knowledge-base with content to convert.
+license: MIT
+---
+
+# Knowledge Base Construction
+
+Convert the user's content directly into a structured Markdown knowledge base. Don't ask clarifying questions unless the content is genuinely unusable (e.g. empty or unintelligible) — infer structure, terminology, and grouping from what's given, and note any gaps inline rather than blocking on them.
+
+## Workflow
+
+1. Read the content and split it into coherent concepts (one idea per file — prefer several small linked files over one large one).
+1. Create new directory with a name relative to the content user provide (e.g. `italian-food`, `turbocharge`, `formula-one`, etc. ).
+1. Group concepts into type directories that fit the material's own structure. Let the content dictate the categories — e.g. `recipes/`, `policies/`, `species/`, `procedures/`, `terms/`, `people/`, `events/` — whatever natural groupings emerge. Don't force a data/tech taxonomy onto non-technical content.
+1. Write each file using the format below, preserving the user's own terminology and facts. Never invent details, numbers, names, or steps that weren't given.
+1. Add relative Markdown links between related concepts.
+1. Save all files under an input directory your just created.
+
+## Example file tree
+
+```
+cooking/
+  recipes/
+    italian/
+      lasagna.md
+      carbonara.md
+    japanese/
+      ramen.md
+      sushi.md
+  techniques/
+    knife-skills.md
+    emulsion.md
+  ingredients/
+    eggs.md
+    flour-types.md
+  faq.md
+  common-mistake.md
+```
+
+- Root files (e.g. `faq.md`) are allowed
+- File can be nested as deep as necessary and semantically sound.
+
+## File format
+
+```markdown
+# Clear Concept Title
+
+> One-sentence factual summary.
+
+Body: context, details, steps, examples, caveats — whatever fits the concept.
+```
+
+- First line `# Title`, then a `>` description, then body detail.
+- Use headings, lists, tables, or code blocks as they help retrieval — not all concepts need all of these.
+- One concept per file. Directory name per type (e.g. `recipes/lasagna.md` → type `recipes`).
+- Lowercase, stable filenames, no spaces.
+- No `index.md`, `log.md`, `README.md` as concepts — bundler reserves these.
+- No YAML frontmatter in source files
+
+Do not fabricate any information on your own, use only what user provided to you.

{okf_cli-0.4.1 → okf_cli-0.4.5}/src/okf/commands/bundle.py

@@ -78,11 +78,13 @@ def bundle(
     input_dir: str = typer.Argument(
         ..., help="Source directory of plain markdown files"
     ),
-    output_dir: str = typer.Argument(
-        "bundled", help="Output directory for the OKF bundle (default: bundled)"
+    output_dir: str | None = typer.Argument(
+        None,
+        help="Output directory for the OKF bundle "
+        "(default: <input-dir>_knowledge_base)",
     ),
     default_type: str = typer.Option(
-        None, help="Type for root-level files (skip root files if omitted)"
+        None, help="Type for root-level files (default: input directory name)"
     ),
     force: bool = typer.Option(
         False, "--force", "-f", help="Overwrite output directory if it exists"
@@ -97,15 +99,26 @@ def bundle(
 
     Each .md file must start with '# Title' followed by a '>' description block.
     Directory name determines the concept 'type'. Root-level files need --default-type.
-    If output-dir is omitted, defaults to 'bundled'.
+    If output-dir is omitted, defaults to '<input-dir>_knowledge_base'.
     """
     src = Path(input_dir)
+
+    if output_dir is None:
+        output_dir = f"{src.name}_knowledge_base"
+
     dst = Path(output_dir)
 
     if not src.is_dir():
         typer.echo(f"Error: input directory '{input_dir}' not found", err=True)
         raise typer.Exit(code=1)
 
+    if src.resolve() == dst.resolve():
+        typer.echo(
+            "Error: input and output directories must be different",
+            err=True,
+        )
+        raise typer.Exit(code=1)
+
     if dst.exists():
         if not force:
             typer.echo(
@@ -149,11 +162,7 @@ def bundle(
         typer.echo("No markdown files found (excluding index.md, log.md)", err=True)
         raise typer.Exit(code=1)
 
-    planned_files = [
-        f
-        for f in md_files
-        if not (f.relative_to(src).parent == Path(".") and default_type is None)
-    ]
+    planned_files = md_files
     planned_rels = [f.relative_to(src) for f in planned_files]
     bundle_targets = {rel.as_posix() for rel in planned_rels}
 
@@ -207,13 +216,7 @@ def bundle(
 
         # Determine type
         if rel.parent == Path("."):
-            if default_type is None:
-                typer.echo(
-                    f"Warning: Skipping {rel} — root-level file needs --default-type",
-                    err=True,
-                )
-                continue
-            type_name = default_type
+            type_name = default_type or src.name
         else:
             type_name = rel.parent.name
 
@@ -295,13 +298,24 @@ def bundle(
     # Generate AGENTS.md at bundle root
     (dst / "AGENTS.md").write_text(
         f"# Knowledge Base: {dst.name}\n\n"
-        f"You are in an OKF knowledge base called **{dst.name}**.\n\n"
+        f"You are in an OKF (Open Knowledge Format) knowledge base called "
+        f"**{dst.name}**. OKF is a structured markdown format where each "
+        f"`.md` file is a concept with YAML frontmatter (`type`, `title`, "
+        f"`description`) and cross-links between related concepts.\n\n"
+        "## Instructions\n\n"
+        "- **Answer from this knowledge base only.** Use the concepts and "
+        "links here as your source of truth.\n"
+        "- **If the answer is not in the knowledge base, say so directly.** "
+        "Do not fabricate, guess, or pull from external knowledge.\n\n"
         "## Getting Started\n\n"
-        "Read [index.md](index.md) first — it lists all concepts and subdirectories.\n\n"
+        "Read [index.md](index.md) first — it lists all concepts "
+        "and subdirectories.\n\n"
         "## Navigation\n\n"
         "- Follow markdown links between concepts.\n"
-        "- Each `.md` file has YAML frontmatter with `type`, `title`, `description`.\n"
+        "- Each `.md` file has YAML frontmatter with `type`, `title`, "
+        "`description`.\n"
         "- Subdirectories group related concepts by topic.\n"
-        "- Cross-links (e.g. `[Customers](/tables/customers.md)`) express relationships.\n",
+        "- Cross-links (e.g. `[Customers](/tables/customers.md)`) "
+        "express relationships.\n",
         encoding="utf-8",
     )

{okf_cli-0.4.1 → okf_cli-0.4.5}/tests/cli/test_bundle.py

@@ -82,7 +82,8 @@ def test_bundle_root_file_with_default_type(tmp_path: Path):
     assert "[Standalone](standalone.md)" in root_idx
 
 
-def test_bundle_skip_root_file_without_default(tmp_path: Path, capsys):
+def test_bundle_root_file_uses_input_dir_name_without_default(tmp_path: Path):
+    """Root-level files get type from input directory name when --default-type omitted."""
     src = tmp_path / "notes"
     dst = tmp_path / "bundle"
     src.mkdir()
@@ -97,14 +98,15 @@ def test_bundle_skip_root_file_without_default(tmp_path: Path, capsys):
     result = runner.invoke(app, ["bundle", str(src), str(dst)])
     assert result.exit_code == 0, result.output
 
-    assert not (dst / "standalone.md").exists()
+    assert (dst / "standalone.md").exists()
+    stand = (dst / "standalone.md").read_text()
+    assert 'type: "notes"' in stand
     assert (dst / "tables" / "data.md").exists()
-    assert "Skipping" in result.output
 
-    # Root index should list subdir only (standalone was skipped)
+    # Root index should list subdir + root file
     root_idx = (dst / "index.md").read_text()
     assert "[tables](tables/)" in root_idx
-    assert "[Standalone" not in root_idx
+    assert "[Standalone](standalone.md)" in root_idx
 
 
 def test_bundle_lenient_parse(tmp_path: Path):
@@ -178,6 +180,16 @@ def test_bundle_refuses_overwrite_without_force(tmp_path: Path):
     assert "--force" in result.output
 
 
+def test_bundle_refuses_same_input_and_output_dir(tmp_path: Path):
+    src = tmp_path / "notes"
+    src.mkdir()
+    _write_fixture(src, {"tables/a.md": "# A\n\n> Desc.\n"})
+
+    result = runner.invoke(app, ["bundle", str(src), str(src), "--force"])
+    assert result.exit_code == 1, result.output
+    assert "must be different" in result.output
+
+
 def test_bundle_no_md_files(tmp_path: Path):
     src = tmp_path / "notes"
     dst = tmp_path / "bundle"
@@ -262,7 +274,7 @@ def test_bundle_okfignore_skips_matching_files(tmp_path: Path):
     assert (dst / "tables" / "customers.md").exists()
 
 
-def test_bundle_okfignore_skips_root_file_before_default_type_check(tmp_path: Path):
+def test_bundle_okfignore_skips_root_file(tmp_path: Path):
     src = tmp_path / "notes"
     dst = tmp_path / "bundle"
     src.mkdir()
@@ -277,7 +289,6 @@ def test_bundle_okfignore_skips_root_file_before_default_type_check(tmp_path: Pa
 
     result = runner.invoke(app, ["bundle", str(src), str(dst)])
     assert result.exit_code == 0, result.output
-    assert "root-level file needs --default-type" not in result.output
     assert not (dst / "standalone.md").exists()
     assert (dst / "tables" / "data.md").exists()
 
@@ -342,7 +353,9 @@ def test_bundle_warns_broken_local_markdown_link(tmp_path: Path):
     _write_fixture(
         src,
         {
-            "tables/orders.md": "# Orders\n\n> One row.\n\nSee [Customers](customers.md).",
+            "tables/orders.md": (
+                "# Orders\n\n> One row.\n\nSee [Customers](customers.md)."
+            ),
         },
     )
 
@@ -358,8 +371,12 @@ def test_bundle_accepts_valid_relative_and_absolute_local_links(tmp_path: Path):
     _write_fixture(
         src,
         {
-            "tables/orders.md": "# Orders\n\n> One row.\n\nSee [Customers](./customers.md).",
-            "tables/customers.md": "# Customers\n\n> All customers.\n\nSee [Orders](/tables/orders.md).",
+            "tables/orders.md": (
+                "# Orders\n\n> One row.\n\nSee [Customers](./customers.md)."
+            ),
+            "tables/customers.md": (
+                "# Customers\n\n> All customers.\n\nSee [Orders](/tables/orders.md)."
+            ),
         },
     )
 
@@ -397,7 +414,9 @@ def test_bundle_warns_markdown_link_outside_bundle(tmp_path: Path):
     _write_fixture(
         src,
         {
-            "tables/orders.md": "# Orders\n\n> One row.\n\nSee [Secret](../../secret.md).",
+            "tables/orders.md": (
+                "# Orders\n\n> One row.\n\nSee [Secret](../../secret.md)."
+            ),
         },
     )
 
@@ -413,7 +432,9 @@ def test_bundle_strict_links_fails_on_broken_local_link(tmp_path: Path):
     _write_fixture(
         src,
         {
-            "tables/orders.md": "# Orders\n\n> One row.\n\nSee [Customers](customers.md).",
+            "tables/orders.md": (
+                "# Orders\n\n> One row.\n\nSee [Customers](customers.md)."
+            ),
         },
     )
 
@@ -429,8 +450,10 @@ def test_bundle_strict_links_passes_with_valid_local_links(tmp_path: Path):
     _write_fixture(
         src,
         {
-            "tables/orders.md": "# Orders\n\n> One row.\n\nSee [Customers](./customers.md).",
-            "tables/customers.md": "# Customers\n\n> All customers.\n\nBody.",
+            "tables/orders.md": (
+                "# Orders\n\n> One row.\n\nSee [Customers](./customers.md)."
+            ),
+            "tables/customers.md": ("# Customers\n\n> All customers.\n\nBody."),
         },
     )
 

{okf_cli-0.4.1 → okf_cli-0.4.5}/tests/e2e/test_e2e.py

@@ -62,7 +62,8 @@ def test_bundle_default_type_includes_root_files(tmp_path: Path):
     assert 'type: "reference"' in content
 
 
-def test_bundle_skips_root_files_without_default_type(tmp_path: Path):
+def test_bundle_root_files_get_type_from_input_dir(tmp_path: Path):
+    """Root-level files get type from input directory name when --default-type omitted."""
     src = tmp_path / "src"
     dst = tmp_path / "out"
     src.mkdir()
@@ -76,8 +77,9 @@ def test_bundle_skips_root_files_without_default_type(tmp_path: Path):
 
     result = runner.invoke(app, ["bundle", str(src), str(dst)])
     assert result.exit_code == 0, result.output
-    assert not (dst / "domain.md").exists()
-    assert "root-level file needs --default-type" in result.output
+    assert (dst / "domain.md").exists()
+    content = (dst / "domain.md").read_text()
+    assert 'type: "src"' in content
 
 
 def test_bundle_force_overwrites(tmp_path: Path):
@@ -248,7 +250,9 @@ def test_bundle_warns_broken_link(tmp_path: Path):
     _write(
         src,
         {
-            "tables/orders.md": "# Orders\n\n> One row.\n\nSee [Customers](customers.md).",
+            "tables/orders.md": (
+                "# Orders\n\n> One row.\n\nSee [Customers](customers.md)."
+            ),
         },
     )
 
@@ -264,7 +268,9 @@ def test_bundle_accepts_valid_links(tmp_path: Path):
     _write(
         src,
         {
-            "tables/orders.md": "# Orders\n\n> One row.\n\nSee [Customers](./customers.md).",
+            "tables/orders.md": (
+                "# Orders\n\n> One row.\n\nSee [Customers](./customers.md)."
+            ),
             "tables/customers.md": "# Customers\n\n> All.\n\nBody.",
         },
     )
@@ -740,7 +746,10 @@ def test_show_valid_concept(tmp_path: Path):
 
 
 def test_show_with_md_extension_appended(tmp_path: Path):
-    """show always appends .md — passing tables/orders.md looks for tables/orders.md.md."""
+    """show always appends .md.
+
+    Passing tables/orders.md looks for tables/orders.md.md.
+    """
     d = tmp_path / "bundle"
     d.mkdir()
     _write(d, {"tables/orders.md": "---\ntype: tables\n---\n\nBody."})

{okf_cli-0.4.1 → okf_cli-0.4.5}/uv.lock

@@ -52,7 +52,7 @@ wheels = [
 
 [[package]]
 name = "okf-cli"
-version = "0.4.1"
+version = "0.4.5"
 source = { editable = "." }
 dependencies = [
     { name = "pyyaml" },

okf_cli-0.4.1/.last-update.json

@@ -1,5 +0,0 @@
-{
-  "lastHead": "ddca03b",
-  "lastRun": "2026-07-11",
-  "mode": "update"
-}

okf_cli-0.4.1/skills/writing-knowledge-base/SKILL.md

@@ -1,127 +0,0 @@
----
-name: writing-knowledge-base
-description: Help a domain expert turn their knowledge into a plain Markdown knowledge base that can be bundled into OKF with `okf bundle`. Use reference/knowledge-base.md for content guidance and reference/example/ for structure and writing style.
-license: MIT
----
-
-# Knowledge Base Construction
-
-Help a domain expert turn their knowledge into a plain Markdown knowledge base that can be bundled into OKF with `okf bundle`. Use `reference/knowledge-base.md` for content guidance and `reference/example/` for structure and writing style.
-
-## Role
-
-Act as facilitator and editor, not an authority on the domain.
-
-- Ask focused questions when facts, scope, ownership, terminology, or relationships are unclear.
-- Never invent domain facts, metrics, schemas, URLs, SLAs, or procedures.
-- Preserve the expert's terminology and meaning; improve structure and clarity only.
-- Prefer several small, linked concepts over one large document.
-
-## Workflow
-
-1. Learn the domain, audience, and intended use of the knowledge base.
-
-1. Identify concepts and group them into directories such as `datasets/`, `tables/`, `playbooks/`, or other domain-appropriate types.
-
-1. Propose a file tree before writing many files. Get expert agreement on names and grouping.
-
-1. Draft or update one concept at a time. Show the draft and ask for corrections.
-
-1. Add links between related concepts using relative Markdown links.
-
-1. Review for missing context, contradictions, stale-looking operational details, and unsupported assumptions.
-
-1. Keep source files under a chosen input directory, following `reference/example/`.
-
-1. When ready, explain how to bundle and validate:
-
-   ```bash
-   okf bundle <input-dir> <output-dir> --default-type reference
-   okf validate <output-dir>
-   ```
-
-   Use `--default-type` only when root-level files exist. Prefer placing concepts in named directories.
-
-## References
-
-Read these files before drafting when more detail is needed:
-
-- `reference/knowledge-base.md` — what a good knowledge base and concept file look like.
-- `reference/example/` — complete example input structure copied from this project.
-
-## File format
-
-Every concept should normally use this format:
-
-```markdown
-# Clear Concept Title
-
-> One-sentence summary of this concept.
-
-Body content with useful context, structure, examples, procedures, or schema.
-```
-
-Rules:
-
-- First line: `# Title`.
-- Follow with a `>` description block. Keep it concise and factual.
-- Put detailed knowledge in the body after the description.
-- Use headings, lists, tables, and code blocks where they help retrieval.
-- Use one file per concept.
-- Directory name becomes OKF `type`: `tables/orders.md` becomes type `tables`.
-- Use lowercase, stable, descriptive filenames. Avoid spaces when possible.
-- Do not create `index.md`, `log.md`, or `README.md` as concepts in source input; bundling reserves them.
-- Do not add frontmatter to source files. `okf bundle` generates it.
-
-## Concept guidance
-
-For data assets, capture:
-
-- What asset contains and why it exists.
-- Grain or unit of each record.
-- Ownership and consumers, if known.
-- Schema with field name, type, and meaning.
-- Keys, joins, partitions, freshness, quality limits, and known caveats.
-
-For processes and playbooks, capture:
-
-- Trigger and scope.
-- Ordered steps.
-- Decision points and expected outcomes.
-- Owners, escalation paths, tools, and safety constraints.
-- Links to related assets and procedures.
-
-For domain concepts, capture:
-
-- Definition and boundaries.
-- Synonyms and terms that should not be confused.
-- Examples and counterexamples.
-- Related concepts and source evidence.
-
-## Questions to ask
-
-Ask only questions that unblock useful writing. Examples:
-
-- Who uses this knowledge and what decision should it support?
-- What is the smallest useful concept here?
-- What does each term mean in this domain?
-- What is the source of truth?
-- What is the record grain, owner, freshness, or SLA?
-- What concepts does this depend on or relate to?
-- What should a reader do when this process fails?
-- Which details are confirmed, approximate, deprecated, or unknown?
-
-## Quality check
-
-Before declaring the knowledge base ready, check:
-
-- Every concept has a title and one-sentence description.
-- Each file contains one coherent concept.
-- Directory grouping reflects meaningful concept types.
-- Links point to the correct relative files.
-- No facts were added without expert confirmation.
-- Procedures include ownership and failure handling where relevant.
-- Tables include field meaning, not only field names and types.
-- Unknown or disputed details are visible.
-- Source remains readable as plain Markdown.
-- Generated output passes `okf validate <output-dir>`.

okf_cli-0.4.1/skills/writing-knowledge-base/reference/example/README.md

@@ -1,12 +0,0 @@
-# OKF Example
-
-This directory contains plain markdown files written by domain experts.
-Run `okf bundle` to convert them into an OKF-conformant knowledge bundle.
-
-```bash
-# From repo root:
-uv run okf bundle example output-bundle
-
-# With a default type for root-level files (if any):
-uv run okf bundle example output-bundle --default-type reference
-```

okf_cli-0.4.1/skills/writing-knowledge-base/reference/example/datasets/sales.md

@@ -1,7 +0,0 @@
-# Sales Dataset
-
-> All sales-related tables for the retail business.
-
-Contains transactional data from both online and in-store channels.
-
-Key tables include [orders](../tables/orders.md) and [customers](../tables/customers.md).

okf_cli-0.4.1/skills/writing-knowledge-base/reference/example/domain.md

@@ -1,6 +0,0 @@
-# Our Domain
-
-> What is our domain of interest
-
-Our domain of interest is to allow domain expert to easily shared their
-knowledge with OKF bundle.

okf_cli-0.4.1/skills/writing-knowledge-base/reference/example/loose/deep/no-heading.md

@@ -1,4 +0,0 @@
-I am a file deep in a subdirectory with no heading at all.
-
-Type comes from the directory name, title is omitted, and description is
-derived from this body text.

okf_cli-0.4.1/skills/writing-knowledge-base/reference/example/loose/no-desc.md

@@ -1,6 +0,0 @@
-# Has Title But No Desc
-
-This file has a proper `# Title` but no `>` blockquote description.
-
-It should still be bundled: title extracted normally, description taken
-from the first 80 characters of the body as a fallback.

okf_cli-0.4.1/skills/writing-knowledge-base/reference/example/loose/no-title.md

@@ -1,5 +0,0 @@
-No heading at all — this file has no `# Title` line and no `>` description block.
-
-It should still be bundled: title omitted from frontmatter, description
-derived from the first 80 characters of this body text verbatim, with
-newlines collapsed to spaces.

okf_cli-0.4.1/skills/writing-knowledge-base/reference/example/playbooks/incident-response.md

@@ -1,14 +0,0 @@
-# Data Freshness Incident
-
-> Steps to triage a freshness alert on the orders pipeline.
-
-## Trigger
-
-A freshness alert fires when the [orders](../tables/orders.md) table lags more than 30 minutes behind its expected SLA.
-
-## Steps
-
-1. Check the ingestion job dashboard.
-1. Verify upstream source connectivity.
-1. Inspect the [Sales Dataset](../datasets/sales.md) for recent changes.
-1. Notify the data engineering team if the issue persists.

okf_cli-0.4.1/skills/writing-knowledge-base/reference/example/playbooks/oncall-guide.md

@@ -1,13 +0,0 @@
-# On-call Guide
-
-> Quick reference for on-call data engineers.
-
-## Channels
-
-- **Critical alerts**: PagerDuty
-- **Team chat**: #data-eng on Slack
-- **Escalation**: Contact the data engineering lead
-
-## Common Issues
-
-See [Incident Response](incident-response.md) for data freshness issues.

okf_cli-0.4.1/skills/writing-knowledge-base/reference/example/tables/customers.md

@@ -1,16 +0,0 @@
-# Customers
-
-> One row per registered customer.
-
-## Schema
-
-| Column      | Type      | Description                |
-| ----------- | --------- | -------------------------- |
-| customer_id | STRING    | Unique customer identifier |
-| name        | STRING    | Customer display name      |
-| email       | STRING    | Customer email address     |
-| created_at  | TIMESTAMP | Account creation date      |
-
-## Notes
-
-Referenced by [orders](orders.md) via `customer_id`.

okf_cli-0.4.1/skills/writing-knowledge-base/reference/example/tables/orders.md

@@ -1,16 +0,0 @@
-# Customer Orders
-
-> One row per completed customer order across all channels.
-
-## Schema
-
-| Column      | Type      | Description               |
-| ----------- | --------- | ------------------------- |
-| order_id    | STRING    | Unique order identifier   |
-| customer_id | STRING    | Foreign key to customers  |
-| total_usd   | NUMERIC   | Order total in USD        |
-| placed_at   | TIMESTAMP | When the order was placed |
-
-## Notes
-
-Part of the [Sales Dataset](../datasets/sales.md). Joined with [customers](customers.md) on `customer_id`.

okf_cli-0.4.1/skills/writing-knowledge-base/reference/example/tables/partitions/2026/q1/jan/january.md

@@ -1,5 +0,0 @@
-# January 2026
-
-> Orders placed in January 2026.
-
-Monthly slice of the [daily](../../../daily.md) partition.

okf_cli-0.4.1/skills/writing-knowledge-base/reference/example/tables/partitions/daily.md

@@ -1,12 +0,0 @@
-# Daily Partition
-
-> One partition per day for the orders table.
-
-Part of the [orders](../../tables/orders.md) table's partitioning scheme.
-
-## Schema
-
-| Column         | Type  | Description                     |
-| -------------- | ----- | ------------------------------- |
-| partition_date | DATE  | The date of this partition      |
-| row_count      | INT64 | Number of rows in the partition |

okf_cli-0.4.1/skills/writing-knowledge-base/reference/knowledge-base.md

@@ -1,65 +0,0 @@
-# Knowledge Base Reference
-
-Knowledge base is plain Markdown organized as small, linked concepts.
-Domain expert supplies facts. Agent supplies structure, questions, and editing.
-
-## Basic concept
-
-```markdown
-# Customer Orders
-
-> One row per completed customer order across all channels.
-
-## Schema
-
-| Column | Type | Description |
-|--------|------|-------------|
-| order_id | STRING | Unique order identifier |
-| customer_id | STRING | Foreign key to customers |
-| total_usd | NUMERIC | Order total in USD |
-
-## Notes
-
-Part of the [Sales Dataset](../datasets/sales.md).
-```
-
-## Source structure
-
-```text
-knowledge-base/
-├── domain.md                    # Optional root-level domain overview
-├── datasets/                    # Dataset concepts
-│   └── sales.md
-├── tables/                      # Table concepts
-│   ├── customers.md
-│   ├── orders.md
-│   └── partitions/
-│       └── daily.md
-└── playbooks/                   # Operational procedure concepts
-    ├── incident-response.md
-    └── oncall-guide.md
-```
-
-Directory names become OKF concept types when bundled. For example,
-`tables/orders.md` becomes a concept with type `tables` and ID
-`tables/orders`.
-
-## Writing rules
-
-- Use one coherent concept per file.
-- Start with `# Title`.
-- Follow title with a concise `>` description.
-- Put detail in the body.
-- Link related concepts with relative Markdown links.
-- Use lowercase, stable filenames.
-- Do not add YAML frontmatter to source files; bundler generates it.
-
-## Data concept checklist
-
-Capture what asset contains, record grain, owner, consumers, schema, keys,
-joins, partitions, freshness, quality limits, and caveats when known.
-
-## Playbook checklist
-
-Capture trigger, scope, ordered steps, decisions, expected outcomes, owners,
-escalation, tools, and failure handling when known.