okf-cli 0.3.1__tar.gz → 0.4.3__tar.gz

okf_cli-0.4.3/.last-update.json

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

{okf_cli-0.3.1 → okf_cli-0.4.3}/AGENTS.md

@@ -2,6 +2,16 @@
 
 This file is for AI agents (and humans) picking up work on `okf-cli`.
 
+## OpenWiki (read first)
+
+This repository has docs in `openwiki/`.
+
+Start here:
+
+- [OpenWiki quickstart](openwiki/quickstart.md)
+
+Then follow links to architecture, workflows, domain model, operations, and testing notes relevant to task.
+
 ## Project overview
 
 `okf-cli` is a Python CLI that converts plain markdown directories into
@@ -9,6 +19,7 @@ This file is for AI agents (and humans) picking up work on `okf-cli`.
 inspect/validate them.
 
 - **Input:** plain `.md` files starting with `# Title` and a `>` description block.
+  `bundle` also supports optional `.okfignore` in input root.
 - **Output:** OKF-conformant markdown with YAML frontmatter, per-directory `index.md` files.
 - **Operations:** `bundle`, `list`, `show`, `validate`.
 
@@ -75,12 +86,12 @@ okf-cli
 
 ### Commands
 
-| Command | Input expected | Behavior |
-|---|---|---|
-| `bundle` | non-conformant plain markdown dir | generates OKF bundle; skips `index.md`, `log.md`, `README.md` with warnings; root files need `--default-type`; requires `--force` to overwrite existing output |
-| `list` | OKF-conformant bundle | prints concept IDs; exits 1 if dir is not conformant |
-| `show` | OKF-conformant bundle | prints concept file by ID; exits 1 if dir is not conformant |
-| `validate` | any directory | prints conformance errors and summary per §9 |
+| Command    | Input expected                    | Behavior                                                                                                                                                                                                                                                                 |
+| ---------- | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `bundle`   | non-conformant plain markdown dir | generates OKF bundle; skips `index.md`, `log.md`, `README.md` with warnings; skips `.okfignore`-matched files; checks local `.md` links (warn by default, fail with `--strict-links`); root files need `--default-type`; requires `--force` to overwrite existing output |
+| `list`     | OKF-conformant bundle             | prints concept IDs; exits 1 if dir is not conformant                                                                                                                                                                                                                     |
+| `show`     | OKF-conformant bundle             | prints concept file by ID; exits 1 if dir is not conformant                                                                                                                                                                                                              |
+| `validate` | any directory                     | prints conformance errors and summary per §9                                                                                                                                                                                                                             |
 
 ## Key conventions
 
@@ -92,14 +103,31 @@ okf-cli
   they only treat `index.md` and `log.md` as reserved per the spec.
 - `README.md` can be a valid concept in an OKF bundle.
 
+### Link checks in `bundle`
+
+- `bundle` scans markdown body links for local `.md` targets.
+- Supports relative (`./x.md`, `../x.md`) and bundle-root (`/dir/x.md`) links.
+- Ignores external links (scheme URLs like `https:`/`mailto:`), fragment-only links, directory links, and non-`.md` targets.
+- Default behavior: emit warnings for missing local targets or targets outside bundle.
+- `--strict-links`: treat those link issues as fatal and exit non-zero.
+
+### `.okfignore` (bundle only)
+
+- Location: input directory root (`<input-dir>/.okfignore`).
+- Format: one bundle-relative markdown path per line.
+  - Example: `tables/orders.md`, `smoke-ignore.md`
+- Blank lines and lines starting with `#` are ignored.
+- Matching is exact path match only (no glob, no negation).
+- If `.okfignore` is non-UTF-8, `bundle` exits with error.
+
 ### OKF conformance (§9)
 
 1. Every non-reserved `.md` must have parseable YAML frontmatter.
-2. Every frontmatter must contain a non-empty `type` string.
-3. Reserved filenames (`index.md`, `log.md`) follow structure per §6/§7 when present.
+1. Every frontmatter must contain a non-empty `type` string.
+1. Reserved filenames (`index.md`, `log.md`) follow structure per §6/§7 when present.
    - `index.md` must not contain frontmatter (§6), except root `index.md` may contain only `okf_version` (§11).
    - `log.md` must not contain frontmatter (§7).
-4. All files must be valid UTF-8.
+1. All files must be valid UTF-8.
 
 `check_conformance()` is the source of truth for this logic.
 
@@ -137,18 +165,20 @@ Add tests for new behavior in `tests/test_cli.py`. Existing patterns:
 
 ```bash
 uv run okf bundle example bundled --default-type reference --force
+uv run okf bundle example bundled --default-type reference --force --strict-links
 uv run okf validate bundled
 uv run okf list bundled
 ```
 
 `bundled/` is gitignored; it is only a local artifact. Use `--force` for re-runs.
+If `example/.okfignore` exists, `bundle` will skip matched files.
 
 ### Add a new CLI command
 
 1. Create `src/okf/commands/<name>.py` with a function taking `typer` arguments.
-2. Import and register it in `src/okf/cli.py` with `app.command()(fn)` or
+1. Import and register it in `src/okf/cli.py` with `app.command()(fn)` or
    `app.command("alias")(fn)`.
-3. Add tests in `tests/test_cli.py`.
+1. Add tests in `tests/test_cli.py`.
 
 ### Modify conformance behavior
 
@@ -161,3 +191,15 @@ Update `check_conformance()` in `src/okf/core.py`, then ensure
 - Do not add abstractions "for later".
 - Use `Path` from `pathlib`, not string path manipulation.
 - Use `uv` for all package/runtime commands.
+
+## OpenWiki
+
+This repository has documentation located in the /openwiki directory.
+
+Start here:
+
+- [OpenWiki quickstart](openwiki/quickstart.md)
+
+OpenWiki includes repository overview, architecture notes, workflows, domain concepts, operations, integrations, testing guidance, and source maps.
+
+When working in this repository, read the OpenWiki quickstart first, then follow its links to the relevant architecture, workflow, domain, operation, and testing notes.

{okf_cli-0.3.1 → okf_cli-0.4.3}/OKF_SPEC.md

@@ -12,7 +12,7 @@ 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
 
@@ -33,9 +33,9 @@ of structural conventions needed to make a knowledge corpus
 ### 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
+1. Inform how **consumption agents** should read and traverse it.
+1. Facilitate **exchange** of knowledge across systems and organizations.
+1. Standardize the small number of **required** fields that must be
    present for content to be meaningfully consumed.
 
 ### Non-goals
@@ -45,7 +45,7 @@ of structural conventions needed to make a knowledge corpus
 - Replacing domain-specific schemas (Avro, Protobuf, OpenAPI, etc.) —
   OKF *references* them; it does not subsume them.
 
----
+______________________________________________________________________
 
 ## 2. Terminology
 
@@ -66,7 +66,7 @@ of structural conventions needed to make a knowledge corpus
 - **Citation** — A link from a concept to an external source that
   supports a claim in the body.
 
----
+______________________________________________________________________
 
 ## 3. Bundle Structure
 
@@ -97,10 +97,10 @@ A bundle MAY be distributed as:
 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.                                |
+| Filename   | Purpose                    |
+| ---------- | -------------------------- |
+| `index.md` | Directory listing. See §6. |
+| `log.md`   | Update history. See §7.    |
 
 All other `.md` files are concept documents.
 
@@ -109,7 +109,7 @@ 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
 
@@ -117,7 +117,7 @@ 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.
+1. A **markdown body**, containing free-form content.
 
 ### 4.1 Frontmatter
 
@@ -170,11 +170,11 @@ 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.   |
+| 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
 
@@ -228,7 +228,7 @@ its expected SLA. See the [orders table](/tables/orders.md).
 2. …
 ```
 
----
+______________________________________________________________________
 
 ## 5. Cross-linking
 
@@ -266,7 +266,7 @@ 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
 
@@ -293,7 +293,7 @@ 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)
 
@@ -317,7 +317,7 @@ 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
 
@@ -336,7 +336,7 @@ 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
 
@@ -344,8 +344,8 @@ 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
+1. Every frontmatter block contains a non-empty `type` field.
+1. 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
@@ -361,7 +361,7 @@ 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
 
@@ -377,7 +377,7 @@ OKF is intentionally close to several established patterns:
 OKF differs primarily in being **specified** — pinning down the small
 set of rules needed for interoperability without dictating tooling.
 
----
+______________________________________________________________________
 
 ## 11. Versioning
 
@@ -395,7 +395,7 @@ 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
 

{okf_cli-0.3.1 → okf_cli-0.4.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: okf-cli
-Version: 0.3.1
+Version: 0.4.3
 Summary: Open Knowledge Format tooling
 License: MIT License
         
@@ -53,22 +53,45 @@ uv run okf --help
 ### `okf bundle` — convert plain markdown to OKF bundle
 
 ```
-okf bundle <input-dir> [output-dir] [--default-type <name>] [--force]
+okf bundle <input-dir> [output-dir] [--default-type <name>] [--force] [--strict-links]
 ```
 
-| Argument | Description |
-|---|---|
-| `input-dir` | Directory of plain `.md` files |
-| `output-dir` | Target directory (default: `bundled`) |
-| `--default-type` | Type for root-level files (skip root files if omitted) |
-| `--force`, `-f` | Overwrite output directory if it exists |
+| Argument         | Description                                                                  |
+| ---------------- | ---------------------------------------------------------------------------- |
+| `input-dir`      | Directory of plain `.md` files                                               |
+| `output-dir`     | Target directory (default: `bundled`)                                        |
+| `--default-type` | Type for root-level files (skip root files if omitted)                       |
+| `--force`, `-f`  | Overwrite output directory if it exists                                      |
+| `--strict-links` | Fail if local markdown links point outside bundle or to missing `.md` target |
 
 ```bash
 okf bundle example --default-type reference  # first run → bundled/
 okf bundle example --default-type reference --force  # re-run
+okf bundle example --default-type reference --force --strict-links  # fail on broken local .md links
 cat bundled/tables/orders.md
 ```
 
+`.okfignore` (bundle only):
+
+- Put `.okfignore` in `input-dir`.
+- Add bundle-relative markdown paths to skip, one per line.
+- Blank lines and `#` comments ignored.
+- Matching is exact path match (no glob, no negation).
+
+```text
+# example/.okfignore
+smoke-ignore.md
+tables/orders.md
+```
+
+Local link checks during `bundle`:
+
+- Scans markdown body links to local `.md` targets.
+- Supports relative links (`./x.md`, `../x.md`) and bundle-root links (`/tables/x.md`).
+- Ignores external links (`https:`, `mailto:`), fragment-only links (`#section`), directory links, and non-`.md` targets.
+- Default mode prints warnings for missing targets or links resolving outside bundle.
+- `--strict-links` turns those warnings into a non-zero exit (`Error: strict link check failed`).
+
 ### `okf list` — list concept IDs in a bundle
 
 ```
@@ -155,19 +178,20 @@ Everything after the description block is preserved unchanged.
 
 Files that don't follow the strict format are still bundled best-effort:
 
-| Condition | Behavior |
-|---|---|
-| No `# Title` on line 1 | Title omitted from frontmatter |
-| No `>` description block | Description derived from first 80 chars of body ("…" if truncated) |
-| Root-level file without `--default-type` | Skip file, warn, continue |
+| Condition                                | Behavior                                                           |
+| ---------------------------------------- | ------------------------------------------------------------------ |
+| No `# Title` on line 1                   | Title omitted from frontmatter                                     |
+| No `>` description block                 | Description derived from first 80 chars of body ("…" if truncated) |
+| Root-level file without `--default-type` | Skip file, warn, continue                                          |
 
 **Rules:**
 
-| Rule | Why |
-|---|---|
-| Folder name = concept type | `tables/orders.md` → `type: "tables"` |
-| Only `.md` files processed | Non-`.md` files ignored |
+| Rule                                                  | Why                                                                                                                                                                                                                         |
+| ----------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Folder name = concept type                            | `tables/orders.md` → `type: "tables"`                                                                                                                                                                                       |
+| Only `.md` files processed                            | Non-`.md` files ignored                                                                                                                                                                                                     |
 | `index.md`, `log.md`, `README.md` skipped in `bundle` | Input may contain repo artifacts; these are not concepts. `bundle` warns when it skips them. Other commands (`list`, `show`, `validate`) operate on conformant OKF bundles where only `index.md` and `log.md` are reserved. |
+| `.okfignore` entries skipped in `bundle`              | Add bundle-relative markdown paths (e.g. `tables/orders.md`) to skip conversion for selected files. Blank lines and `#` comments are ignored.                                                                               |
 
 Root files need `--default-type`. Otherwise put files in named folders.
 
@@ -175,11 +199,12 @@ See the [`example/`](example/) directory for a sample of how to structure files.
 
 ## How `bundle` works
 
-1. Walk `input-dir` for `.md` files (skip reserved names)
-2. Extract `title` from `#` on line 1, `description` from `>` block. If strict format not met, falls back: title omitted if absent, description from first 80 chars of body
-3. Set `type` from parent dir name, `timestamp` from file mtime
-4. Write concept files with YAML frontmatter (title field omitted if empty)
-5. Generate `index.md` per directory — `# Contents` for files, `# Directories` for subdirs (recursive)
+1. Walk `input-dir` for `.md` files (skip `.okfignore` matches and reserved names)
+1. Extract `title` from `#` on line 1, `description` from `>` block. If strict format not met, falls back: title omitted if absent, description from first 80 chars of body
+1. Check local markdown links against planned bundle targets (warn by default, or fail with `--strict-links`)
+1. Set `type` from parent dir name, `timestamp` from file mtime
+1. Write concept files with YAML frontmatter (title field omitted if empty)
+1. Generate `index.md` per directory — `# Contents` for files, `# Directories` for subdirs (recursive)
 
 ## Output
 

{okf_cli-0.3.1 → okf_cli-0.4.3}/README.md

@@ -22,22 +22,45 @@ uv run okf --help
 ### `okf bundle` — convert plain markdown to OKF bundle
 
 ```
-okf bundle <input-dir> [output-dir] [--default-type <name>] [--force]
+okf bundle <input-dir> [output-dir] [--default-type <name>] [--force] [--strict-links]
 ```
 
-| Argument | Description |
-|---|---|
-| `input-dir` | Directory of plain `.md` files |
-| `output-dir` | Target directory (default: `bundled`) |
-| `--default-type` | Type for root-level files (skip root files if omitted) |
-| `--force`, `-f` | Overwrite output directory if it exists |
+| Argument         | Description                                                                  |
+| ---------------- | ---------------------------------------------------------------------------- |
+| `input-dir`      | Directory of plain `.md` files                                               |
+| `output-dir`     | Target directory (default: `bundled`)                                        |
+| `--default-type` | Type for root-level files (skip root files if omitted)                       |
+| `--force`, `-f`  | Overwrite output directory if it exists                                      |
+| `--strict-links` | Fail if local markdown links point outside bundle or to missing `.md` target |
 
 ```bash
 okf bundle example --default-type reference  # first run → bundled/
 okf bundle example --default-type reference --force  # re-run
+okf bundle example --default-type reference --force --strict-links  # fail on broken local .md links
 cat bundled/tables/orders.md
 ```
 
+`.okfignore` (bundle only):
+
+- Put `.okfignore` in `input-dir`.
+- Add bundle-relative markdown paths to skip, one per line.
+- Blank lines and `#` comments ignored.
+- Matching is exact path match (no glob, no negation).
+
+```text
+# example/.okfignore
+smoke-ignore.md
+tables/orders.md
+```
+
+Local link checks during `bundle`:
+
+- Scans markdown body links to local `.md` targets.
+- Supports relative links (`./x.md`, `../x.md`) and bundle-root links (`/tables/x.md`).
+- Ignores external links (`https:`, `mailto:`), fragment-only links (`#section`), directory links, and non-`.md` targets.
+- Default mode prints warnings for missing targets or links resolving outside bundle.
+- `--strict-links` turns those warnings into a non-zero exit (`Error: strict link check failed`).
+
 ### `okf list` — list concept IDs in a bundle
 
 ```
@@ -124,19 +147,20 @@ Everything after the description block is preserved unchanged.
 
 Files that don't follow the strict format are still bundled best-effort:
 
-| Condition | Behavior |
-|---|---|
-| No `# Title` on line 1 | Title omitted from frontmatter |
-| No `>` description block | Description derived from first 80 chars of body ("…" if truncated) |
-| Root-level file without `--default-type` | Skip file, warn, continue |
+| Condition                                | Behavior                                                           |
+| ---------------------------------------- | ------------------------------------------------------------------ |
+| No `# Title` on line 1                   | Title omitted from frontmatter                                     |
+| No `>` description block                 | Description derived from first 80 chars of body ("…" if truncated) |
+| Root-level file without `--default-type` | Skip file, warn, continue                                          |
 
 **Rules:**
 
-| Rule | Why |
-|---|---|
-| Folder name = concept type | `tables/orders.md` → `type: "tables"` |
-| Only `.md` files processed | Non-`.md` files ignored |
+| Rule                                                  | Why                                                                                                                                                                                                                         |
+| ----------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Folder name = concept type                            | `tables/orders.md` → `type: "tables"`                                                                                                                                                                                       |
+| Only `.md` files processed                            | Non-`.md` files ignored                                                                                                                                                                                                     |
 | `index.md`, `log.md`, `README.md` skipped in `bundle` | Input may contain repo artifacts; these are not concepts. `bundle` warns when it skips them. Other commands (`list`, `show`, `validate`) operate on conformant OKF bundles where only `index.md` and `log.md` are reserved. |
+| `.okfignore` entries skipped in `bundle`              | Add bundle-relative markdown paths (e.g. `tables/orders.md`) to skip conversion for selected files. Blank lines and `#` comments are ignored.                                                                               |
 
 Root files need `--default-type`. Otherwise put files in named folders.
 
@@ -144,11 +168,12 @@ See the [`example/`](example/) directory for a sample of how to structure files.
 
 ## How `bundle` works
 
-1. Walk `input-dir` for `.md` files (skip reserved names)
-2. Extract `title` from `#` on line 1, `description` from `>` block. If strict format not met, falls back: title omitted if absent, description from first 80 chars of body
-3. Set `type` from parent dir name, `timestamp` from file mtime
-4. Write concept files with YAML frontmatter (title field omitted if empty)
-5. Generate `index.md` per directory — `# Contents` for files, `# Directories` for subdirs (recursive)
+1. Walk `input-dir` for `.md` files (skip `.okfignore` matches and reserved names)
+1. Extract `title` from `#` on line 1, `description` from `>` block. If strict format not met, falls back: title omitted if absent, description from first 80 chars of body
+1. Check local markdown links against planned bundle targets (warn by default, or fail with `--strict-links`)
+1. Set `type` from parent dir name, `timestamp` from file mtime
+1. Write concept files with YAML frontmatter (title field omitted if empty)
+1. Generate `index.md` per directory — `# Contents` for files, `# Directories` for subdirs (recursive)
 
 ## Output
 

okf_cli-0.4.3/example/.okfignore

@@ -0,0 +1,3 @@
+# smoke test ignore entries
+smoke-ignore.md
+tables/orders.md

{okf_cli-0.3.1 → okf_cli-0.4.3}/example/playbooks/incident-response.md

@@ -9,6 +9,6 @@ A freshness alert fires when the [orders](../tables/orders.md) table lags more t
 ## Steps
 
 1. Check the ingestion job dashboard.
-2. Verify upstream source connectivity.
-3. Inspect the [Sales Dataset](../datasets/sales.md) for recent changes.
-4. Notify the data engineering team if the issue persists.
+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.3/example/smoke-ignore.md

@@ -0,0 +1,5 @@
+# Smoke Ignore
+
+> This file should be ignored by bundle during smoke test.
+
+If this appears in output, ignore logic failed.

okf_cli-0.4.3/example/tables/customers.md

@@ -0,0 +1,16 @@
+# 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.3/example/tables/orders.md

@@ -0,0 +1,17 @@
+# 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`.
+Also see [Missing Concept](missing.md) and [Outside](../../secret.md).

okf_cli-0.4.3/example/tables/partitions/daily.md

@@ -0,0 +1,12 @@
+# 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.3/openwiki/architecture.md

@@ -0,0 +1,72 @@
+# Architecture
+
+## Runtime shape
+
+`okf-cli` is intentionally small: Typer command layer + shared core helpers.
+
+- CLI app creation and command registration: `src/okf/cli.py`
+- Core format/parsing/conformance helpers: `src/okf/core.py`
+- Command handlers:
+  - `bundle`: `src/okf/commands/bundle.py`
+  - `validate`: `src/okf/commands/validate.py`
+  - `list`: `src/okf/commands/list.py`
+  - `show`: `src/okf/commands/show.py`
+
+Why this split exists: business rules live once in `core.py`, while command files mostly handle IO/CLI errors.
+
+## Command execution flow
+
+### `okf bundle`
+
+1. Read source directory + optional `.okfignore` (`_load_okfignore`).
+1. Walk `*.md`, skipping reserved names and ignored paths.
+1. Parse each markdown file via `parse_md` (strict first, lenient fallback).
+1. Scan markdown body links via `_iter_links` / `_resolve_md_target` — warns on missing or out-of-bundle targets; `--strict-links` makes these fatal.
+1. Build YAML frontmatter via `build_frontmatter`.
+1. Write transformed files and generate `index.md` per directory.
+1. Write `AGENTS.md` at output root with navigation guidance for the knowledge base.
+
+Source: `src/okf/commands/bundle.py`, `src/okf/core.py`.
+
+### `okf validate`
+
+1. Ensure target directory exists and has markdown files.
+1. Call `check_conformance` once.
+1. Print warnings/errors + summary, exit non-zero on errors.
+
+Source: `src/okf/commands/validate.py`, `src/okf/core.py`.
+
+### `okf list` and `okf show`
+
+Both commands first run `check_conformance`. If directory is non-conformant, they refuse to proceed.
+
+Reason: reading APIs should not return misleading data from broken bundles.
+
+Source: `src/okf/commands/list.py`, `src/okf/commands/show.py`.
+
+## Shared invariants
+
+- 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`).
+- Non-UTF-8 markdown is a conformance error.
+- `type` frontmatter is required and must be non-empty for non-reserved concept files.
+
+Source: `src/okf/core.py`.
+
+## Evolution notes (from git history)
+
+Major behavior shifts:
+
+- project started bundling-focused, then added `validate`/`list`/`show` workflow;
+- frontmatter parsing/conformance matured to real YAML parsing and shared conformance gating;
+- markdown parsing in bundling became lenient to tolerate imperfect source docs;
+- `.okfignore` added to allow selective exclusions without moving/deleting source files.
+
+Evidence: `git log -- src/okf/core.py`, `git log -- src/okf/commands/bundle.py`, top-level `git log --oneline`.
+
+## Extension points
+
+- New command: add `src/okf/commands/<name>.py`, register in `src/okf/cli.py`, add CLI tests under `tests/cli/`.
+- New conformance rule: implement in `check_conformance` (`src/okf/core.py`) and update validate/list/show expectations.
+- New metadata field support: no schema migration required; parser already tolerates extra YAML keys.