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

okf_cli-0.4.7/.last-update.json

@@ -0,0 +1 @@
+{"head": "b0a76b5d97d2d46ab19d4fc4149be3efb4dc0228", "timestamp": "2025-07-15T19:10:00Z"}

okf_cli-0.4.7/AGENTS.md

@@ -0,0 +1,82 @@
+# AGENTS.md — okf-cli contributor context
+
+This file is for AI agents (and humans) picking up work on `okf-cli`.
+
+## OpenWiki (read first)
+
+This repository has documentation in `openwiki/`.
+
+Start here:
+
+- [OpenWiki quickstart](openwiki/quickstart.md)
+
+Then follow links to architecture, workflows, domain model, operations, and testing notes relevant to task.
+
+## Tech stack
+
+- Python 3.11+
+- Package/venv manager: **uv**
+- CLI framework: **typer**
+- YAML parsing: **pyyaml**
+- Tests: **pytest**
+- Lint/format: **ruff** (via `uvx ruff check .` / `uvx ruff format .`)
+- Build: hatchling (configured in `pyproject.toml`)
+
+Always use `uv` for dependency sync and running commands:
+
+```bash
+uv sync                  # install/sync deps
+uv run pytest -q           # run tests
+uv run okf --help          # run CLI
+```
+
+## Project layout
+
+```
+okf-cli
+├── .github/workflows/test.yml # CI (pytest on 3.11)
+├── OKF_SPEC.md              # OKF v0.1 specification
+├── pyproject.toml           # project metadata + deps
+├── uv.lock                  # uv lockfile
+├── src/okf/
+│   ├── cli.py               # Typer entrypoint, registers commands
+│   ├── api.py               # programmatic Python API (all business logic)
+│   ├── core.py              # shared parsing/formatting/conformance
+│   └── commands/
+│       ├── bundle.py        # thin wrapper → api.bundle()
+│       ├── list.py          # thin wrapper → api.list_concepts()
+│       ├── show.py          # thin wrapper → api.show_concept()
+│       └── validate.py      # thin wrapper → api.validate()
+└── tests/
+    ├── test_api.py          # API unit/integration tests
+    ├── test_cli.py          # CLI exit code/error message tests
+    └── test_core.py         # core helper unit tests
+```
+
+## Common tasks
+
+### Regenerate the example bundle
+
+```bash
+uv run okf bundle example bundled --default-type reference --force
+uv run okf validate bundled
+```
+
+`bundled/` is gitignored. Use `--force` for re-runs.
+
+### Add a new CLI command
+
+1. Create `src/okf/commands/<name>.py` with a function taking `typer` arguments.
+1. Import and register it in `src/okf/cli.py` with `app.command()(fn)`.
+1. Add tests in `tests/test_cli.py`.
+
+### Modify conformance behavior
+
+Update `check_conformance()` in `src/okf/core.py`, then ensure `validate`, `list`, and `show` all behave consistently.
+
+## Style guidelines
+
+- Keep changes minimal. Prefer stdlib/installed dependencies over new ones.
+- Do not add abstractions "for later".
+- Use `Path` from `pathlib`, not string path manipulation.
+- Use `uv` for all package/runtime commands.

okf_cli-0.4.7/PKG-INFO

@@ -0,0 +1,169 @@
+Metadata-Version: 2.4
+Name: okf-cli
+Version: 0.4.7
+Summary: Open Knowledge Format tooling
+License: MIT License
+        
+        Copyright (c) 2026 Dheerapat Tookkane
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: pyyaml>=6
+Requires-Dist: typer>=0.15
+Description-Content-Type: text/markdown
+
+# okf-cli — Open Knowledge Format tooling
+
+Converts plain markdown into [OKF](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md)-conformant knowledge bundles. Domain experts write the content, `okf bundle` generates frontmatter, type, timestamps, and index files.
+
+Also validates bundles, lists concept IDs, and reads concepts by ID.
+
+## Install
+
+```bash
+uv tool install okf-cli
+```
+
+### Dev quickstart
+
+```bash
+uv sync
+uv run okf --help
+```
+
+## Commands
+
+### `okf bundle` — convert plain markdown to OKF bundle
+
+```
+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                                      |
+| `--strict-links` | Fail if local markdown links point outside bundle or to missing `.md` target |
+
+```bash
+okf bundle example --default-type reference  # → bundled/
+okf bundle example --default-type reference --force --strict-links
+```
+
+**`.okfignore`**: put in `input-dir` root; one bundle-relative `.md` path per line. Exact match only (no glob).
+
+**Link checking**: scans body links to local `.md` targets. Missing or out-of-bundle links warn by default, fail with `--strict-links`.
+
+### `okf list` — list concept IDs in a bundle
+
+```
+okf list <directory>
+```
+
+Prints concept IDs (path without `.md`). Requires valid OKF bundle.
+
+```bash
+okf list bundled/
+# datasets/sales
+# tables/orders
+```
+
+### `okf show` — read a concept by ID
+
+```
+okf show <directory> <concept-id>
+```
+
+Prints full concept contents (frontmatter + body). Concept IDs as printed by `okf list`. Guards against path traversal.
+
+### `okf validate` — check OKF conformance
+
+```
+okf validate <directory>
+```
+
+Checks OKF v0.1 §9 conformance: frontmatter required, `type` required, reserved filenames follow spec structure, UTF-8 required.
+
+```bash
+okf validate bundled/
+# 16 files: 16 ok
+```
+
+## Input format
+
+### Strict (recommended)
+
+```markdown
+# Title
+
+> Description
+```
+
+### Lenient fallback
+
+Files without strict format are bundled best-effort: title omitted if absent, description synthesized from first 80 chars of body.
+
+| 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` | Repo artifacts; not OKF concepts. `list`/`show`/`validate` only reserve `index.md` and `log.md`. |
+| `.okfignore` entries skipped                          | Skip selected files without moving them.                                                         |
+
+Root files need `--default-type`. See [`example/`](example/) for sample structure.
+
+## Output
+
+Each concept becomes a markdown file with YAML frontmatter:
+
+```yaml
+---
+type: "tables"
+title: "Customer Orders"
+description: "One row per completed customer order across all channels."
+timestamp: "2026-07-04T15:06:51+00:00"
+---
+
+Original body preserved as-is.
+```
+
+Every directory gets an `index.md` listing files and subdirs.
+
+## OKF Conformance
+
+Generated bundles conform to [OKF v0.1](OKF_SPEC.md) (§9): frontmatter required, non-empty `type`, reserved filenames follow spec structure.
+
+## Project layout
+
+```
+okf-cli
+├── .github/workflows/test.yml  # CI
+├── OKF_SPEC.md                 # OKF specification
+├── pyproject.toml              # uv-managed Python project
+├── src/okf/
+│   ├── cli.py            # Typer entrypoint
+│   ├── api.py            # Programmatic Python API
+│   ├── core.py           # Shared parsing/formatting
+│   └── commands/         # bundle, list, show, validate
+├── tests/                # pytest suite
+└── example/              # Sample input markdown
+```

okf_cli-0.4.7/README.md

@@ -0,0 +1,138 @@
+# okf-cli — Open Knowledge Format tooling
+
+Converts plain markdown into [OKF](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md)-conformant knowledge bundles. Domain experts write the content, `okf bundle` generates frontmatter, type, timestamps, and index files.
+
+Also validates bundles, lists concept IDs, and reads concepts by ID.
+
+## Install
+
+```bash
+uv tool install okf-cli
+```
+
+### Dev quickstart
+
+```bash
+uv sync
+uv run okf --help
+```
+
+## Commands
+
+### `okf bundle` — convert plain markdown to OKF bundle
+
+```
+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                                      |
+| `--strict-links` | Fail if local markdown links point outside bundle or to missing `.md` target |
+
+```bash
+okf bundle example --default-type reference  # → bundled/
+okf bundle example --default-type reference --force --strict-links
+```
+
+**`.okfignore`**: put in `input-dir` root; one bundle-relative `.md` path per line. Exact match only (no glob).
+
+**Link checking**: scans body links to local `.md` targets. Missing or out-of-bundle links warn by default, fail with `--strict-links`.
+
+### `okf list` — list concept IDs in a bundle
+
+```
+okf list <directory>
+```
+
+Prints concept IDs (path without `.md`). Requires valid OKF bundle.
+
+```bash
+okf list bundled/
+# datasets/sales
+# tables/orders
+```
+
+### `okf show` — read a concept by ID
+
+```
+okf show <directory> <concept-id>
+```
+
+Prints full concept contents (frontmatter + body). Concept IDs as printed by `okf list`. Guards against path traversal.
+
+### `okf validate` — check OKF conformance
+
+```
+okf validate <directory>
+```
+
+Checks OKF v0.1 §9 conformance: frontmatter required, `type` required, reserved filenames follow spec structure, UTF-8 required.
+
+```bash
+okf validate bundled/
+# 16 files: 16 ok
+```
+
+## Input format
+
+### Strict (recommended)
+
+```markdown
+# Title
+
+> Description
+```
+
+### Lenient fallback
+
+Files without strict format are bundled best-effort: title omitted if absent, description synthesized from first 80 chars of body.
+
+| 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` | Repo artifacts; not OKF concepts. `list`/`show`/`validate` only reserve `index.md` and `log.md`. |
+| `.okfignore` entries skipped                          | Skip selected files without moving them.                                                         |
+
+Root files need `--default-type`. See [`example/`](example/) for sample structure.
+
+## Output
+
+Each concept becomes a markdown file with YAML frontmatter:
+
+```yaml
+---
+type: "tables"
+title: "Customer Orders"
+description: "One row per completed customer order across all channels."
+timestamp: "2026-07-04T15:06:51+00:00"
+---
+
+Original body preserved as-is.
+```
+
+Every directory gets an `index.md` listing files and subdirs.
+
+## OKF Conformance
+
+Generated bundles conform to [OKF v0.1](OKF_SPEC.md) (§9): frontmatter required, non-empty `type`, reserved filenames follow spec structure.
+
+## Project layout
+
+```
+okf-cli
+├── .github/workflows/test.yml  # CI
+├── OKF_SPEC.md                 # OKF specification
+├── pyproject.toml              # uv-managed Python project
+├── src/okf/
+│   ├── cli.py            # Typer entrypoint
+│   ├── api.py            # Programmatic Python API
+│   ├── core.py           # Shared parsing/formatting
+│   └── commands/         # bundle, list, show, validate
+├── tests/                # pytest suite
+└── example/              # Sample input markdown
+```

okf_cli-0.4.7/openwiki/architecture.md

@@ -0,0 +1,96 @@
+# Architecture
+
+## Runtime shape
+
+`okf-cli` has a three-layer architecture:
+
+- **CLI layer** (`src/okf/cli.py`) — Typer app creation, command registration, `--version` callback.
+- **API layer** (`src/okf/api.py`) — programmatic Python functions, all business logic lives here.
+- **Core layer** (`src/okf/core.py`) — shared parsing, formatting, conformance helpers.
+- **Command wrappers** (`src/okf/commands/`) — thin IO/error bridges from CLI args to API calls.
+
+Why this split: the API layer is the canonical home for all logic. Commands handle only Typer argument parsing, error display, and exit codes. `core.py` is pure utility with no side effects.
+
+## Key modules
+
+### `src/okf/api.py` — programmatic API
+
+Public functions and return types:
+
+| Function                                       | Returns          | Key behavior                                                                  |
+| ---------------------------------------------- | ---------------- | ----------------------------------------------------------------------------- |
+| `bundle(input_dir, output_dir, ...)`           | `BundleResult`   | Full bundle pipeline with link checking, `.okfignore`, `AGENTS.md` generation |
+| `convert_file(input_file, output_file, type_)` | `BundleResult`   | Convert single markdown file to OKF concept (timestamp from mtime)            |
+| `convert_content(content, output_file, type_)` | `BundleResult`   | Convert raw markdown string to OKF concept (no timestamp)                     |
+| `list_concepts(bundle_dir)`                    | `list[str]`      | Conformance-gated concept ID listing                                          |
+| `show_concept(bundle_dir, concept_id)`         | `ConceptContent` | Conformance-gated concept read with path traversal guard                      |
+| `validate(bundle_dir)`                         | `ValidateResult` | Conformance check with `.ok` property                                         |
+
+Internal helpers (not public API): `_iter_links`, `_resolve_md_target`, `_load_okfignore`, `_generate_indexes`, `_write_concept`.
+
+### `src/okf/core.py` — shared utilities
+
+- `RESERVED` — filenames `bundle` skips: `index.md`, `log.md`, `readme.md`.
+- `SPEC_RESERVED` — spec-level reserved names: `index.md`, `log.md`, `agents.md`.
+- `build_frontmatter(type_, title, description, timestamp)` — YAML frontmatter via JSON-escaped values.
+- `parse_md(text)` — extracts title/description/body; strict first, lenient fallback.
+- `parse_frontmatter(text)` — parses YAML frontmatter, returns `None` for invalid.
+- `check_conformance(directory)` — validates OKF §9, returns `(errors, warnings)`.
+
+### Command wrappers (`src/okf/commands/`)
+
+Each file imports from `okf.api` and calls the corresponding function, translating exceptions to Typer exit codes. No business logic.
+
+## Command execution flow
+
+### `okf bundle` (via `api.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.
+
+### `okf validate` (via `api.validate()`)
+
+1. Ensure target directory exists and has markdown files.
+1. Call `check_conformance` once.
+1. Return `ValidateResult` with file count, errors, and warnings.
+
+### `okf list` and `okf show` (via `api.list_concepts()` / `api.show_concept()`)
+
+Both functions first run `check_conformance`. If directory is non-conformant, they raise `ValueError`.
+
+Reason: reading APIs should not return misleading data from broken bundles.
+
+## Shared invariants
+
+- Reserved name handling differs by phase:
+  - Bundling phase skips `index.md`, `log.md`, `README.md` (`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.
+
+Source: `src/okf/core.py` (constants), `src/okf/api.py` (enforcement).
+
+## 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;
+- single-file conversion (`convert_file`, `convert_content`) added for programmatic use without full directory bundling;
+- `bundle()` internal logic refactored to use shared `_write_concept` helper.
+
+Evidence: `git log -- src/okf/core.py`, `git log -- src/okf/commands/bundle.py`, top-level `git log --oneline`.
+
+## Extension points
+
+- New API function: add to `src/okf/api.py` with typed return, add tests in `tests/test_api.py`.
+- New command: add thin wrapper in `src/okf/commands/`, register in `src/okf/cli.py`, add CLI tests in `tests/test_cli.py`.
+- New conformance rule: implement in `check_conformance` (`src/okf/core.py`) and update API/validate expectations.
+- New metadata field support: no schema migration required; parser already tolerates extra YAML keys.

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

@@ -19,7 +19,7 @@ Markdown file with YAML frontmatter at top:
 - required for non-reserved files: `type` (non-empty string)
 - optional but common: `title`, `description`, `timestamp`, plus arbitrary producer-defined keys
 
-Implementation: `parse_frontmatter`, `check_conformance` in `src/okf/core.py`.
+Implementation: `parse_frontmatter`, `check_conformance` in `src/okf/core.py`. API returns parsed data via `ConceptContent` dataclass.
 
 ### Concept ID
 
@@ -27,7 +27,15 @@ Bundle-relative path without `.md` suffix.
 
 - Example: `tables/orders.md` -> `tables/orders`.
 
-Implementation: `src/okf/commands/list.py`, `src/okf/commands/show.py`.
+Implementation: `api.list_concepts()`, `api.show_concept()` in `src/okf/api.py`.
+
+### Result types (API)
+
+`src/okf/api.py` defines typed return values:
+
+- `BundleResult` — `files_written`, `output_dir`, `warnings`, `errors`
+- `ValidateResult` — `total_files`, `errors`, `warnings`, `ok` (property)
+- `ConceptContent` — `frontmatter` (dict), `body`, `raw`
 
 ### Reserved filenames
 

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

@@ -14,6 +14,7 @@ Packaging and runtime metadata: `pyproject.toml`.
 Key points:
 
 - CLI script entrypoint: `okf = "okf.cli:app"`
+- Python API: `from okf.api import bundle, list_concepts, show_concept, validate`
 - Runtime deps: `typer`, `pyyaml`
 - Dev deps include `pytest`, `ruff`
 

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

@@ -3,11 +3,14 @@
 `okf-cli` converts plain markdown directories into Open Knowledge Format (OKF) bundles, then validates and reads those bundles.
 
 - CLI entrypoint: `src/okf/cli.py`
+- Programmatic Python API: `src/okf/api.py`
 - Shared parsing/conformance logic: `src/okf/core.py`
-- Commands: `src/okf/commands/bundle.py`, `src/okf/commands/validate.py`, `src/okf/commands/list.py`, `src/okf/commands/show.py`
+- Commands (thin wrappers): `src/okf/commands/bundle.py`, `src/okf/commands/validate.py`, `src/okf/commands/list.py`, `src/okf/commands/show.py`
 
 ## Start in 5 minutes
 
+### CLI
+
 ```bash
 uv sync
 uv run okf --help
@@ -18,6 +21,30 @@ uv run okf show example_knowledge_base tables/customers
 uv run okf bundle example --default-type reference --force --strict-links
 ```
 
+### Python API
+
+```python
+from okf.api import (
+    bundle, convert_file, convert_content,
+    list_concepts, show_concept, validate,
+)
+
+# Full directory bundle
+result = bundle("example", "out", default_type="reference", force=True)
+assert result.errors == []
+
+# Single-file conversions
+convert_file("example/tables/orders.md", "out/tables/orders.md", type_="tables")
+convert_content("# Title\n\n> Desc\n\nBody.", "out/single.md", type_="reference")
+
+concepts = list_concepts("out")
+concept = show_concept("out", "tables/customers")
+print(concept.body)
+
+report = validate("out")
+assert report.ok
+```
+
 Why this sequence:
 
 1. `bundle` transforms raw markdown into OKF structure.

okf_cli-0.4.7/openwiki/testing.md

@@ -0,0 +1,75 @@
+# Testing
+
+## Test suite map
+
+- API unit/integration tests: `tests/test_api.py`
+  - `TestBundle` — bundling via `api.bundle()`, link checking, `.okfignore`, lenient parsing, `AGENTS.md` generation
+  - `TestListConcepts` — listing via `api.list_concepts()`, reserved file handling
+  - `TestShowConcept` — reading via `api.show_concept()`, path traversal guard
+  - `TestValidate` — conformance checks via `api.validate()`, all §9 rule variants
+  - `TestWorkflow` — cross-command pipeline (bundle → validate/list/show)
+- Core unit tests: `tests/test_core.py`
+  - parsing helpers (`parse_md`, `parse_frontmatter`)
+  - frontmatter generation (`build_frontmatter`)
+  - conformance engine (`check_conformance`)
+- CLI integration tests: `tests/test_cli.py`
+  - exit codes and error message formatting for all commands
+  - Typer-specific behavior (argument parsing, `--force`, `--strict-links`)
+
+## Run tests
+
+```bash
+uv run pytest -q
+```
+
+## Change-oriented guidance
+
+### If editing `src/okf/api.py`
+
+Run at minimum:
+
+```bash
+uv run pytest -q tests/test_api.py tests/test_cli.py
+```
+
+Reason: API functions are the business logic; CLI tests verify the wrapper layer.
+
+### If editing `src/okf/core.py`
+
+Run at minimum:
+
+```bash
+uv run pytest -q tests/test_core.py tests/test_api.py
+```
+
+Reason: core helpers are used by the API layer.
+
+### If editing command wrappers (`src/okf/commands/*.py`)
+
+Run at minimum:
+
+```bash
+uv run pytest -q tests/test_cli.py
+```
+
+Reason: commands are thin wrappers — CLI tests verify exit codes and error output.
+
+### If editing CLI registration (`src/okf/cli.py`)
+
+Run full suite:
+
+```bash
+uv run pytest -q
+```
+
+## Behaviors with dedicated regression coverage
+
+- `.okfignore` parsing and skip semantics, including non-UTF-8 failure.
+- Lenient parsing fallback when strict markdown format is missing.
+- Reserved filename differences between bundling and spec conformance.
+- Root `index.md` special allowance for `okf_version` only.
+- `list`/`show` hard failure on non-conformant bundles.
+- `show` path traversal guard.
+- Link checking: `_resolve_md_target` path resolution, `--strict-links` fatal mode, missing/out-of-bundle targets.
+
+Primary evidence: `tests/test_api.py`, `tests/test_core.py`, `tests/test_cli.py`.