maestro-case-kit 0.1.0__tar.gz

maestro_case_kit-0.1.0/.gitignore

@@ -0,0 +1,111 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+dist/
+build/
+*.egg
+
+# Virtual environments
+.venv/
+venv/
+ENV/
+
+# Environment variables
+.env
+.env.*
+!.env.example
+
+# IDE
+.idea/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+.mypy_cache/
+
+# Databases (local dev)
+*.db-shm
+*.db-wal
+ruvector.db
+
+# Swarm state (ephemeral)
+.swarm/
+
+# Claude memory (session-specific)
+.claude/memory.db
+
+# Agent-OS session-persistence DB (churns per checkpoint; dir tracked via .keep)
+.agent-os/memory/project_memory.db
+__pycache__/
+
+# UiPath solution per-user debug-overwrite state (generated by `solution project add`)
+maestro_case/clearflow-solution/userProfile/
+
+# Node
+node_modules/
+ui/node_modules/
+ui/.next/
+ui/out/
+
+# Build artifacts
+*.nupkg
+.uipath/
+
+# Coded-agent `uip codedagent init` scaffolding (regenerated per dir; not source)
+agents/*/.agent/
+agents/*/.claude/
+agents/*/AGENTS.md
+agents/*/CLAUDE.md
+agents/*/main.mermaid
+
+# UiPath skills repo (cloned locally, symlinked into .claude/skills etc.)
+.uipath-skills/
+
+# Installed UiPath skills (upstream content, sync via scripts/sync-uipath-skills.sh)
+.claude/skills/uipath-*
+.agents/skills/uipath-*
+.github/skills/uipath-*
+
+# Claude-flow runtime state
+.claude-flow/
+
+# Caches
+.cache/
+
+# Logs
+*.log
+scripts/logs/
+.claude-flow/logs/
+
+# Reference-only assets — never committed (images, PDFs, captured docs, archives).
+# These live under knowledge/ for local reference only.
+*.pdf
+*.png
+*.jpg
+*.jpeg
+*.gif
+*.webp
+# Exception: the architecture diagram is a deliberate committed submission asset
+# (rendered from docs/images/architecture.svg), embedded in README + Devpost.
+!docs/images/architecture.png
+!docs/images/architecture.gif
+*.zip
+knowledge/new_knowledge/
+knowledge/screenshots/studio_web_errors/
+knowledge/agent-harness.zip
+
+# Secret-bearing config — NEVER committed (MCP server API keys, test configs).
+# Tracked previously and purged from history 2026-05-31; keys rotated.
+.mcp.json
+**/test_config.py
+tests/unit/test_config.py

maestro_case_kit-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,44 @@
+# Contributing to Maestro Case Kit
+
+The knowledge layer is the moat — it stays valuable only if entries are accurate,
+version-stamped, and free of any real-world identifiers. Every contribution runs
+through an automated **schema + IP-safety gate** before it can land.
+
+## Add or update a knowledge entry
+
+Entries live in [`src/maestro_case_kit/data/knowledge.json`](src/maestro_case_kit/data/knowledge.json).
+Each entry has this shape:
+
+| Field | Required | Notes |
+|---|---|---|
+| `id` | yes | Stable, unique, UPPER-KEBAB (e.g. `MC-SPAWN-QEM-400300`). |
+| `kind` | yes | `runtime` / `data-fabric` / `hitl` / `cli` / `packaging` / `context-grounding` / ... |
+| `title` | yes | One line. |
+| `surface` | yes | Where it bites (e.g. `Maestro Case spawn JobArguments`). |
+| `symptom` | yes | What the author observes. |
+| `error_signatures` | list | Raw signatures `explain` matches on (`400300`, `still being indexed`); `[]` if silent. |
+| `cause` | yes | Why it happens. |
+| `fix` | yes | The proven workaround. |
+| `proven_on` | yes | Platform/CLI version the behavior was confirmed on (e.g. `1.0.21`). |
+| `resolved_in` | optional | Set when UiPath ships a fix — the entry then drops from active guidance. |
+| `severity` | yes | `high` / `medium` / `low`. |
+| `references` | list | Repo-relative paths or doc URLs. |
+
+**Freshness is a feature.** Do not delete a fixed entry — set `resolved_in` so the
+history survives and `explain --include-resolved` can still surface it.
+
+**IP-safety is zero-tolerance.** No real company, product, patient, or claim names in
+any field. Use generic or fictional placeholders.
+
+## Run the gate locally
+
+```bash
+# Validate the bundled knowledge layer (schema + duplicate ids):
+maestro-case validate-knowledge
+
+# Validate a file against your own denylist (newline-delimited tokens, # comments ok):
+maestro-case validate-knowledge --file path/to/knowledge.json --denylist-file denylist.txt
+```
+
+A non-zero exit means the gate found problems — fix them before opening a PR. Add a
+test for any new validator rule or behavior; `pytest` must be green.

maestro_case_kit-0.1.0/PKG-INFO

@@ -0,0 +1,65 @@
+Metadata-Version: 2.4
+Name: maestro-case-kit
+Version: 0.1.0
+Summary: Agent-native knowledge layer + offline, credential-free static validators for UiPath Maestro Case footguns.
+License: MIT
+Keywords: agent-skills,case-management,linter,maestro,mcp,uipath
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+
+# Maestro Case Kit
+
+Offline, credential-free **knowledge + static validators** for UiPath **Maestro Case /
+Data Fabric / Action Center** footguns. One define-once source, four artifacts: a Go-free
+Python **CLI**, an **MCP server**, a Claude Code **skill**, and an OpenClaw **skill**.
+
+> Built from behaviors discovered while running a multi-stakeholder crisis case end-to-end
+> on UiPath Automation Cloud. The orchestration tier *above* the canvas is unserved by
+> official tooling; this kit makes the hard-won knowledge installable and agent-native.
+
+## Why
+
+- UiPath's coding-agent MCP is a single catch-all `run_command` shell — not typed tools.
+- Maestro Case error codes (`400300`, `160009`, `170015`, ...) return zero search results.
+- Caseplan edits can be silently inert; Data Fabric fields can silently vanish on insert.
+
+This kit encodes those footguns as a **version-stamped knowledge layer** + **CI linters**
+that run with **no UiPath login**.
+
+## Install
+
+```bash
+pipx install maestro-case-kit        # CLI: maestro-case ; MCP: maestro-case-mcp
+```
+
+## Use
+
+```bash
+maestro-case explain 400300                 # error code -> proven cause + fix (offline)
+maestro-case lint   path/to/caseplan-dir    # static V20 lint (stale .bpmn, no start event, ...)
+maestro-case check-spawn path/to/caseplan-dir   # =datafabric.qem in spawn inputs (400300)
+maestro-case check-df  entity-spec.json     # Data Fabric underscore-drop / reserved id
+```
+
+Every command takes `--json` and exits non-zero when it has a finding, so it drops
+straight into CI. See [`SKILL.md`](SKILL.md) for agent-host usage and recipes.
+
+## MCP server
+
+`maestro-case-mcp` speaks newline-delimited JSON-RPC over stdio (no third-party MCP SDK
+dependency) and exposes typed tools: `maestro_case_explain`, `maestro_case_lint`,
+`maestro_case_check_spawn`, `maestro_case_check_df`. Register it with any MCP host.
+
+## One source, many harnesses
+
+`SKILL.md` is the define-once skill source. Fan it out to other coding-agent runtimes
+(Cursor, Codex, Gemini, Copilot, OpenClaw/ClawHub) with a skills converter — e.g.
+`/polyskill` or `npx skills add`. The CLI and MCP server are generated from the same
+shared tool registry (`maestro_case_kit/tools.py`), so a fix lands once and every surface
+inherits it.
+
+## Knowledge entries & contributions
+
+Entries live in `maestro_case_kit/data/knowledge.json`, each stamped with the version it
+was proven on and an optional `resolved_in`. Contributions run through an automated
+IP-safety + schema gate (see `CONTRIBUTING.md`). License: MIT.

maestro_case_kit-0.1.0/README.md

@@ -0,0 +1,56 @@
+# Maestro Case Kit
+
+Offline, credential-free **knowledge + static validators** for UiPath **Maestro Case /
+Data Fabric / Action Center** footguns. One define-once source, four artifacts: a Go-free
+Python **CLI**, an **MCP server**, a Claude Code **skill**, and an OpenClaw **skill**.
+
+> Built from behaviors discovered while running a multi-stakeholder crisis case end-to-end
+> on UiPath Automation Cloud. The orchestration tier *above* the canvas is unserved by
+> official tooling; this kit makes the hard-won knowledge installable and agent-native.
+
+## Why
+
+- UiPath's coding-agent MCP is a single catch-all `run_command` shell — not typed tools.
+- Maestro Case error codes (`400300`, `160009`, `170015`, ...) return zero search results.
+- Caseplan edits can be silently inert; Data Fabric fields can silently vanish on insert.
+
+This kit encodes those footguns as a **version-stamped knowledge layer** + **CI linters**
+that run with **no UiPath login**.
+
+## Install
+
+```bash
+pipx install maestro-case-kit        # CLI: maestro-case ; MCP: maestro-case-mcp
+```
+
+## Use
+
+```bash
+maestro-case explain 400300                 # error code -> proven cause + fix (offline)
+maestro-case lint   path/to/caseplan-dir    # static V20 lint (stale .bpmn, no start event, ...)
+maestro-case check-spawn path/to/caseplan-dir   # =datafabric.qem in spawn inputs (400300)
+maestro-case check-df  entity-spec.json     # Data Fabric underscore-drop / reserved id
+```
+
+Every command takes `--json` and exits non-zero when it has a finding, so it drops
+straight into CI. See [`SKILL.md`](SKILL.md) for agent-host usage and recipes.
+
+## MCP server
+
+`maestro-case-mcp` speaks newline-delimited JSON-RPC over stdio (no third-party MCP SDK
+dependency) and exposes typed tools: `maestro_case_explain`, `maestro_case_lint`,
+`maestro_case_check_spawn`, `maestro_case_check_df`. Register it with any MCP host.
+
+## One source, many harnesses
+
+`SKILL.md` is the define-once skill source. Fan it out to other coding-agent runtimes
+(Cursor, Codex, Gemini, Copilot, OpenClaw/ClawHub) with a skills converter — e.g.
+`/polyskill` or `npx skills add`. The CLI and MCP server are generated from the same
+shared tool registry (`maestro_case_kit/tools.py`), so a fix lands once and every surface
+inherits it.
+
+## Knowledge entries & contributions
+
+Entries live in `maestro_case_kit/data/knowledge.json`, each stamped with the version it
+was proven on and an optional `resolved_in`. Contributions run through an automated
+IP-safety + schema gate (see `CONTRIBUTING.md`). License: MIT.

maestro_case_kit-0.1.0/SKILL.md

@@ -0,0 +1,89 @@
+---
+name: maestro-case-kit
+description: >-
+  Offline, credential-free knowledge + static validators for UiPath Maestro Case
+  footguns. Explain cryptic error codes (400300, 160009, ...) and lint caseplans,
+  spawn inputs, and Data Fabric specs in CI — no UiPath login. Use when authoring,
+  debugging, or reviewing UiPath Maestro Case / Data Fabric / Action Center work.
+license: MIT
+metadata:
+  homepage: https://github.com/mlbrilliance/cascadecare-network-command
+  openclaw: true
+allowed-tools:
+  - Bash
+---
+
+# Maestro Case Kit
+
+A living, version-stamped knowledge layer over undocumented UiPath **Maestro Case /
+Data Fabric / Action Center** footguns, plus credential-free static validators. The
+v1 surface needs **no UiPath login** — it runs offline and in CI. The same surface
+is exposed three ways from one source: a `maestro-case` CLI, an MCP server
+(`maestro-case-mcp`, stdio), and this skill.
+
+## When to use
+
+- An agent or developer hits a cryptic UiPath error code and search returns nothing.
+- Before packing/deploying a Maestro Case, to catch inert-edit footguns in CI.
+- Authoring Data Fabric entities, to avoid silent field-drops.
+
+## Install
+
+```bash
+pipx install maestro-case-kit         # or: pip install maestro-case-kit
+# MCP server (stdio) — register with your agent host:
+#   command: maestro-case-mcp
+```
+
+## Commands (agent-native — every command takes --json and exits non-zero on findings)
+
+- **Explain an error or footgun** (offline knowledge oracle):
+  ```bash
+  maestro-case explain 400300            # error code
+  maestro-case explain underscore        # keyword
+  maestro-case explain 160009 --json     # structured, for agents/CI
+  ```
+- **Lint a caseplan directory** (stale .bpmn, missing start event, dup output vars, bad V20 expressions):
+  ```bash
+  maestro-case lint path/to/caseplan-dir --json
+  ```
+- **Check spawn fan-out** (=datafabric.qem in spawn inputs → runtime 400300):
+  ```bash
+  maestro-case check-spawn path/to/caseplan-dir
+  ```
+- **Check a Data Fabric entity spec** (underscore silent-drop, reserved `id`):
+  ```bash
+  maestro-case check-df entity-spec.json
+  ```
+
+## Recipe — wire the validators into CI
+
+Run the three validators in a pre-deploy job; non-zero exit fails the build before a
+broken caseplan or a data-losing entity ships:
+
+```bash
+maestro-case lint "$CASEPLAN_DIR" \
+  && maestro-case check-spawn "$CASEPLAN_DIR" \
+  && maestro-case check-df "$ENTITY_SPEC"
+```
+
+## Recipe — explain a lint finding
+
+Lint findings carry a rule id that maps to a knowledge entry; pass it to `explain`
+for the full cause + fix:
+
+```bash
+maestro-case lint "$CASEPLAN_DIR" --json | jq -r '.[].entry_id' | sort -u \
+  | xargs -I{} maestro-case explain {}
+```
+
+## Freshness
+
+Every knowledge entry is stamped with the platform/CLI version it was proven on. When
+UiPath fixes a footgun, the entry is marked `resolved_in` and drops from active
+guidance — pass `--include-resolved` to `explain` to see history.
+
+## MCP tools
+
+The MCP server exposes the same surface as typed tools: `maestro_case_explain`,
+`maestro_case_lint`, `maestro_case_check_spawn`, `maestro_case_check_df`.

maestro_case_kit-0.1.0/pyproject.toml

@@ -0,0 +1,26 @@
+[project]
+name = "maestro-case-kit"
+version = "0.1.0"
+description = "Agent-native knowledge layer + offline, credential-free static validators for UiPath Maestro Case footguns."
+readme = "README.md"
+requires-python = ">=3.12"
+license = { text = "MIT" }
+keywords = ["uipath", "maestro", "case-management", "linter", "mcp", "agent-skills"]
+dependencies = []
+
+[project.scripts]
+maestro-case = "maestro_case_kit.cli:main"
+maestro-case-mcp = "maestro_case_kit.mcp_server:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/maestro_case_kit"]
+
+# Standalone test config (when the package is run on its own, post-extraction).
+# The repo-level gate wires this package in via the root pyproject's pythonpath.
+[tool.pytest.ini_options]
+pythonpath = ["src"]
+testpaths = ["tests"]

maestro_case_kit-0.1.0/src/maestro_case_kit/__init__.py

@@ -0,0 +1,9 @@
+"""Maestro Case Kit — agent-native knowledge + offline validators for UiPath Maestro Case.
+
+A living, version-stamped knowledge layer over the undocumented Maestro Case /
+Data Fabric / Action Center footguns surfaced while building a multi-stakeholder
+crisis case, plus credential-free static validators that run in CI. No UiPath
+login required for the v1 surface.
+"""
+
+__version__ = "0.1.0"

maestro_case_kit-0.1.0/src/maestro_case_kit/cli.py

@@ -0,0 +1,178 @@
+"""`maestro-case` CLI — agent-native, offline access to the knowledge layer.
+
+v1 surface: `explain`. Validators (`lint`, `check-spawn`, `check-df`) attach to the
+same parser in later slices. Every subcommand supports ``--json`` for agent/CI use
+and exits non-zero when it has a finding to report.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+from typing import IO
+
+from . import __version__, contribution, knowledge, validators
+
+
+def _print_human(entries: list[knowledge.KnowledgeEntry], stream: IO[str]) -> None:
+    for e in entries:
+        signals = ", ".join(e.error_signatures) or "(no error code — silent behavior)"
+        resolved = f"  resolved_in: {e.resolved_in}" if e.resolved_in else ""
+        print(f"[{e.id}] {e.title}", file=stream)
+        print(f"  surface:   {e.surface}", file=stream)
+        print(f"  signals:   {signals}", file=stream)
+        print(f"  cause:     {e.cause}", file=stream)
+        print(f"  fix:       {e.fix}", file=stream)
+        print(f"  proven_on: {e.proven_on}{resolved}", file=stream)
+        if e.references:
+            print(f"  refs:      {', '.join(e.references)}", file=stream)
+        print("", file=stream)
+
+
+def _cmd_explain(args: argparse.Namespace) -> int:
+    hits = knowledge.find(args.query, include_resolved=args.include_resolved)
+    if args.json:
+        print(json.dumps([e.to_dict() for e in hits], indent=2))
+        return 0 if hits else 1
+    if not hits:
+        print(
+            f"No known Maestro Case footgun matches {args.query!r}. "
+            f"Try an error code (e.g. 400300) or a keyword (e.g. underscore, gate, deploy).",
+            file=sys.stderr,
+        )
+        return 1
+    _print_human(hits, sys.stdout)
+    return 0
+
+
+def _emit_findings(findings: list[validators.Finding], as_json: bool, ok_label: str) -> int:
+    if as_json:
+        print(json.dumps([f.to_dict() for f in findings], indent=2))
+        return 1 if findings else 0
+    if not findings:
+        print(f"OK — {ok_label}")
+        return 0
+    for f in findings:
+        suffix = f"  (explain: {f.entry_id})" if f.entry_id else ""
+        where = f"  @ {f.location}" if f.location else ""
+        print(f"[{f.severity.upper()}] {f.rule_id}: {f.message}{where}{suffix}")
+    print(f"\n{len(findings)} finding(s).")
+    return 1
+
+
+def _cmd_lint(args: argparse.Namespace) -> int:
+    findings = validators.lint_caseplan(args.caseplan_dir)
+    return _emit_findings(findings, args.json, f"no Maestro Case footguns in {args.caseplan_dir}")
+
+
+def _cmd_check_spawn(args: argparse.Namespace) -> int:
+    findings = validators.check_spawn_fanout(args.caseplan_dir)
+    return _emit_findings(findings, args.json, f"no qem spawn-fanout issues in {args.caseplan_dir}")
+
+
+def _cmd_check_df(args: argparse.Namespace) -> int:
+    findings = validators.validate_df_entity(args.spec)
+    return _emit_findings(findings, args.json, f"no Data Fabric field-name traps in {args.spec}")
+
+
+def _cmd_validate_knowledge(args: argparse.Namespace) -> int:
+    denylist: list[str] = []
+    if args.denylist_file:
+        for line in Path(args.denylist_file).read_text(encoding="utf-8").splitlines():
+            token = line.strip()
+            if token and not token.startswith("#"):
+                denylist.append(token)
+    data: object = args.file or {"entries": [e.to_dict() for e in knowledge.load_entries()]}
+    problems = contribution.validate_knowledge(data, denylist)
+    if args.json:
+        print(json.dumps(problems, indent=2))
+        return 1 if problems else 0
+    if not problems:
+        print("OK — knowledge passes the contribution gate.")
+        return 0
+    for problem in problems:
+        print(f"[GATE] {problem}")
+    print(f"\n{len(problems)} problem(s).")
+    return 1
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="maestro-case",
+        description="Knowledge + offline validators for UiPath Maestro Case footguns.",
+    )
+    parser.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+    sub = parser.add_subparsers(dest="command")
+
+    explain = sub.add_parser(
+        "explain",
+        help="Explain a UiPath Maestro Case error code or footgun from the knowledge layer.",
+    )
+    explain.add_argument(
+        "query",
+        help="An error code/signature (e.g. 400300, 160009) or a keyword (e.g. underscore, deploy).",
+    )
+    explain.add_argument("--json", action="store_true", help="Emit structured JSON.")
+    explain.add_argument(
+        "--include-resolved",
+        action="store_true",
+        help="Include entries marked resolved in a later platform version.",
+    )
+    explain.set_defaults(func=_cmd_explain)
+
+    lint = sub.add_parser(
+        "lint",
+        help="Statically lint a caseplan directory for known footguns (offline, no login).",
+    )
+    lint.add_argument(
+        "caseplan_dir",
+        help="Path to a directory containing caseplan.json (and ideally caseplan.json.bpmn).",
+    )
+    lint.add_argument("--json", action="store_true", help="Emit structured JSON findings.")
+    lint.set_defaults(func=_cmd_lint)
+
+    check_spawn = sub.add_parser(
+        "check-spawn",
+        help="Flag =datafabric.qem expressions in spawn inputs (fail at runtime, 400300).",
+    )
+    check_spawn.add_argument("caseplan_dir", help="Path to a directory containing caseplan.json.")
+    check_spawn.add_argument("--json", action="store_true", help="Emit structured JSON findings.")
+    check_spawn.set_defaults(func=_cmd_check_spawn)
+
+    check_df = sub.add_parser(
+        "check-df",
+        help="Lint a Data Fabric entity/field spec for silent-drop and reserved-name traps.",
+    )
+    check_df.add_argument("spec", help="Path to a JSON entity spec ({\"fields\": [...]}).")
+    check_df.add_argument("--json", action="store_true", help="Emit structured JSON findings.")
+    check_df.set_defaults(func=_cmd_check_df)
+
+    vk = sub.add_parser(
+        "validate-knowledge",
+        help="Validate a knowledge file against the schema + an optional IP-safety denylist.",
+    )
+    vk.add_argument("--file", help="Path to a knowledge JSON file (default: the bundled layer).")
+    vk.add_argument(
+        "--denylist-file",
+        help="Optional newline-delimited file of forbidden tokens (# comments allowed).",
+    )
+    vk.add_argument("--json", action="store_true", help="Emit structured JSON problems.")
+    vk.set_defaults(func=_cmd_validate_knowledge)
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    if not getattr(args, "command", None):
+        parser.print_help(sys.stderr)
+        return 2
+    func = args.func
+    assert callable(func)
+    return int(func(args))
+
+
+if __name__ == "__main__":  # pragma: no cover
+    raise SystemExit(main())

maestro_case_kit-0.1.0/src/maestro_case_kit/contribution.py

@@ -0,0 +1,83 @@
+"""Contribution gate — validates knowledge entries against the schema and an
+optional IP-safety denylist, so curation (not the distribution channel) is the moat.
+
+A contributed entry must be well-formed and free of any caller-supplied forbidden
+tokens (e.g. real company names). The denylist is a parameter, not hardcoded, so the
+toolkit stays a general public artifact; a host repo passes its own denylist in CI.
+"""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Iterable
+from pathlib import Path
+
+REQUIRED_FIELDS: tuple[str, ...] = (
+    "id",
+    "kind",
+    "title",
+    "surface",
+    "symptom",
+    "cause",
+    "fix",
+    "proven_on",
+    "severity",
+)
+VALID_SEVERITY: frozenset[str] = frozenset({"high", "medium", "low"})
+_LIST_FIELDS: tuple[str, ...] = ("error_signatures", "references")
+
+
+def _entry_text(entry: dict) -> str:
+    parts: list[str] = []
+    for value in entry.values():
+        if isinstance(value, str):
+            parts.append(value)
+        elif isinstance(value, list):
+            parts.extend(str(item) for item in value)
+    return " ".join(parts).lower()
+
+
+def validate_entry(entry: dict, denylist: Iterable[str] = ()) -> list[str]:
+    """Return a list of problems with one entry; empty means it passes the gate."""
+    problems: list[str] = []
+    for field in REQUIRED_FIELDS:
+        if not entry.get(field):
+            problems.append(f"missing or empty required field: {field}")
+    severity = entry.get("severity")
+    if severity is not None and severity not in VALID_SEVERITY:
+        problems.append(f"invalid severity {severity!r} (expected one of {sorted(VALID_SEVERITY)})")
+    for field in _LIST_FIELDS:
+        if field in entry and not isinstance(entry[field], list):
+            problems.append(f"{field} must be a list")
+    text = _entry_text(entry)
+    entry_id = entry.get("id", "<unknown>")
+    for token in denylist:
+        if token and token.lower() in text:
+            problems.append(f"forbidden token {token!r} in entry {entry_id}")
+    return problems
+
+
+def _coerce_entries(data: object) -> list[dict]:
+    if isinstance(data, (str, Path)):
+        data = json.loads(Path(data).read_text(encoding="utf-8"))
+    if isinstance(data, dict):
+        entries = data.get("entries", [])
+    else:
+        entries = data
+    return [e for e in entries if isinstance(e, dict)] if isinstance(entries, list) else []
+
+
+def validate_knowledge(data: object, denylist: Iterable[str] = ()) -> list[str]:
+    """Validate a knowledge collection (path, {"entries": [...]}, or a list)."""
+    entries = _coerce_entries(data)
+    denylist = tuple(denylist)
+    problems: list[str] = []
+    ids: list[str] = []
+    for entry in entries:
+        problems.extend(validate_entry(entry, denylist))
+        entry_id = entry.get("id")
+        if isinstance(entry_id, str):
+            ids.append(entry_id)
+    for dup in sorted({i for i in ids if ids.count(i) > 1}):
+        problems.append(f"duplicate id: {dup}")
+    return problems