katvan 0.1.0__py3-none-any.whl

katvan/__init__.py

@@ -0,0 +1,11 @@
+"""katvan — maintain sibling-repo docs under one roof on the culture.dev site."""
+
+from importlib.metadata import PackageNotFoundError
+from importlib.metadata import version as _v
+
+try:
+    __version__ = _v("katvan")
+except PackageNotFoundError:  # editable install without metadata
+    __version__ = "0.0.0+local"
+
+__all__ = ["__version__"]

katvan/__main__.py

@@ -0,0 +1,8 @@
+"""Allow running katvan as ``python -m katvan``."""
+
+import sys
+
+from katvan.cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())

katvan/cli/__init__.py

@@ -0,0 +1,131 @@
+"""Unified CLI entry point for katvan.
+
+Top-level globals (``learn``, ``explain``) live under
+:mod:`katvan.cli._commands` and are registered here. Per-noun groups
+(``overview``, ``pull``, ``doctor`` — landing in a later release) will
+register via their own ``register()`` functions following the same pattern.
+
+Error propagation contract
+--------------------------
+Every handler raises :class:`katvan.cli._errors.KatvanError` on failure; the
+top-level ``main()`` catches it via :func:`_dispatch` and routes through
+:mod:`katvan.cli._output`. Unknown exceptions are wrapped into a
+``KatvanError`` so no Python traceback leaks to stderr.
+
+Argparse errors (unknown verb, missing required arg) also route through our
+structured format — ``_KatvanArgumentParser`` overrides ``.error()``. The
+subparsers are built with ``parser_class=_KatvanArgumentParser`` so subparser
+errors follow the same path. Whether the error is emitted as text or JSON
+depends on whether ``--json`` appears in the raw argv (:func:`main` sets
+``_KatvanArgumentParser._json_hint`` before ``parse_args``).
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+
+from katvan import __version__
+from katvan.cli._commands import explain as _explain_cmd
+from katvan.cli._commands import learn as _learn_cmd
+from katvan.cli._errors import EXIT_INTERNAL_ERROR, EXIT_USER_ERROR, KatvanError
+from katvan.cli._output import emit_error
+
+
+class _KatvanArgumentParser(argparse.ArgumentParser):
+    """ArgumentParser that routes errors through :func:`emit_error`.
+
+    Argparse's default error handler writes ``prog: error: <msg>`` to stderr
+    and exits with code 2. That skips our KatvanError plumbing and — crucially
+    — produces no ``hint:`` line, which would make katvan itself fail the
+    rubric's error-propagation bundle. This subclass emits our structured
+    error format instead and exits with :attr:`EXIT_USER_ERROR`.
+
+    JSON mode: parse-time errors happen before ``args.json`` is populated, so
+    we rely on a class-level ``_json_hint`` that :func:`main` pre-populates
+    by scanning the raw argv for ``--json`` / ``--json=…``. Best-effort and
+    shared across all subparser instances (argparse's subparser factory
+    produces instances of the class but doesn't thread state).
+    """
+
+    _json_hint: bool = False
+
+    def error(self, message: str) -> None:  # type: ignore[override]
+        err = KatvanError(
+            code=EXIT_USER_ERROR,
+            message=message,
+            remediation=f"run '{self.prog} --help' to see valid arguments",
+        )
+        emit_error(err, json_mode=type(self)._json_hint)
+        raise SystemExit(err.code)
+
+
+def _argv_has_json(argv: list[str] | None) -> bool:
+    tokens = argv if argv is not None else sys.argv[1:]
+    return any(t == "--json" or t.startswith("--json=") for t in tokens)
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = _KatvanArgumentParser(
+        prog="katvan",
+        description="katvan — maintain sibling-repo docs on the culture.dev site",
+    )
+    parser.add_argument(
+        "--version",
+        action="version",
+        version=f"%(prog)s {__version__}",
+    )
+    # parser_class propagates to every subparser so their .error() routes
+    # through _KatvanArgumentParser too. Without this, a bogus subcommand arg
+    # would hit argparse's default error path (no hint: line, wrong code).
+    sub = parser.add_subparsers(dest="command", parser_class=_KatvanArgumentParser)
+
+    # Globals (top-level, not nested under a noun).
+    _learn_cmd.register(sub)
+    _explain_cmd.register(sub)
+    # The docs verbs — overview / pull / doctor — register here in a later
+    # release once they are ported from the librarian skill.
+
+    return parser
+
+
+def _dispatch(args: argparse.Namespace) -> int:
+    """Invoke the registered handler and translate exceptions to exit codes.
+
+    Handler protocol: a handler may return ``None`` (treated as success,
+    exit 0) or an ``int`` (used directly as the exit code). Failures MUST
+    raise :class:`KatvanError`; any other exception is wrapped into one so no
+    Python traceback leaks.
+    """
+    json_mode = bool(getattr(args, "json", False))
+    try:
+        rc = args.func(args)
+    except KatvanError as err:
+        emit_error(err, json_mode=json_mode)
+        return err.code
+    except Exception as err:  # noqa: BLE001 - last-resort; wrap and route cleanly
+        wrapped = KatvanError(
+            code=EXIT_INTERNAL_ERROR,
+            message=f"unexpected: {err.__class__.__name__}: {err}",
+            remediation="file a bug at https://github.com/agentculture/katvan/issues",
+        )
+        emit_error(wrapped, json_mode=json_mode)
+        return wrapped.code
+    return rc if rc is not None else 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    # Pre-parse peek so argparse-level errors honour --json.
+    _KatvanArgumentParser._json_hint = _argv_has_json(argv)
+    parser = _build_parser()
+    args = parser.parse_args(argv)
+
+    if args.command is None:
+        parser.print_help()
+        return 0
+
+    return _dispatch(args)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

katvan/cli/_commands/explain.py

@@ -0,0 +1,38 @@
+"""``katvan explain <path>...`` — global markdown catalog lookup.
+
+``explain`` is global (not nested under a noun). It takes zero or more path
+tokens and resolves them via :mod:`katvan.explain`. Unknown paths raise
+:class:`KatvanError` with a remediation pointing at ``katvan explain katvan``.
+"""
+
+from __future__ import annotations
+
+import argparse
+
+from katvan.cli._output import emit_result
+from katvan.explain import resolve
+
+
+def cmd_explain(args: argparse.Namespace) -> int:
+    path = tuple(args.path) if args.path else ()
+    markdown = resolve(path)  # raises KatvanError on miss → caught in _dispatch
+    json_mode = bool(getattr(args, "json", False))
+    if json_mode:
+        emit_result({"path": list(path), "markdown": markdown}, json_mode=True)
+    else:
+        emit_result(markdown, json_mode=False)
+    return 0
+
+
+def register(sub: argparse._SubParsersAction) -> None:
+    p = sub.add_parser(
+        "explain",
+        help="Print markdown docs for a noun/verb path (e.g. 'katvan explain learn').",
+    )
+    p.add_argument(
+        "path",
+        nargs="*",
+        help="Command path tokens; empty = root (same as 'katvan').",
+    )
+    p.add_argument("--json", action="store_true", help="Emit structured JSON.")
+    p.set_defaults(func=cmd_explain)

katvan/cli/_commands/learn.py

@@ -0,0 +1,110 @@
+"""``katvan learn`` — the learnability affordance.
+
+Prints a structured self-teaching prompt with enough shape that an agent can
+author its own usage skill without scraping ``--help``. Also supports
+``--json`` for agents that would rather parse structure than text.
+
+Content satisfies the agent-first rubric's learnability bundle: ≥200 chars
+and mentions purpose, command map, exit codes, ``--json``, and ``explain``.
+"""
+
+from __future__ import annotations
+
+import argparse
+
+from katvan import __version__
+from katvan.cli._output import emit_result
+
+_TEXT = """\
+katvan — maintain sibling-repo docs under one roof on the culture.dev site.
+
+Purpose
+-------
+katvan keeps the culture.dev Jekyll site's docs tree coherent: it surveys
+which AgentCulture sibling repos are synced and fresh, pulls their raw
+markdown docs/ trees into site/docs/<repo>/ with Jekyll frontmatter
+injected, and diagnoses doc defects (missing frontmatter, broken links,
+staleness). It is the librarian skill's logic, growing into a real CLI.
+
+Commands
+--------
+  katvan learn              Print this self-teaching prompt. Supports --json.
+  katvan explain <path>...  Print markdown docs for any noun/verb path; the
+                            primary way for an agent to introspect katvan's
+                            grammar. Supports --json.
+
+The docs verbs — overview, pull, and doctor — are coming in a later
+release, ported from the librarian skill.
+
+Universal verb tier (agent-first)
+---------------------------------
+katvan exposes the universal agent-first verbs:
+
+  - learn     — what is this tool?
+  - explain   — what does this command do?
+
+Machine-readable output
+-----------------------
+Every command that produces a listing or report supports --json. Errors in
+JSON mode emit {"code", "message", "remediation"} to stderr. Stdout and
+stderr are never mixed.
+
+Exit-code policy
+----------------
+  0 success
+  1 user-input error (bad flag, bad path, missing arg)
+  2 environment / setup error (registry not found, unreadable file)
+  3 internal/unexpected error (a bug in katvan)
+  4+ reserved
+
+More detail
+-----------
+  katvan explain katvan
+  katvan explain learn
+  katvan explain explain
+
+Homepage: https://github.com/agentculture/katvan
+"""
+
+
+def _as_json_payload() -> dict[str, object]:
+    return {
+        "tool": "katvan",
+        "version": __version__,
+        "purpose": ("Maintain sibling-repo docs under one roof on the culture.dev site."),
+        "commands": [
+            {"path": ["learn"], "summary": "Self-teaching prompt."},
+            {"path": ["explain"], "summary": "Markdown docs by noun/verb path."},
+        ],
+        "coming_soon": [
+            {"path": ["overview"], "summary": "Survey synced/fresh sibling docs."},
+            {"path": ["pull"], "summary": "Sync a sibling's docs/ into the site."},
+            {"path": ["doctor"], "summary": "Detect and report doc defects."},
+        ],
+        "exit_codes": {
+            "0": "success",
+            "1": "user-input error",
+            "2": "environment/setup error",
+            "3": "internal/unexpected error (bug)",
+        },
+        "json_support": True,
+        "explain_pointer": "katvan explain <path> (e.g. 'katvan explain learn')",
+    }
+
+
+def cmd_learn(args: argparse.Namespace) -> int:
+    json_mode = bool(getattr(args, "json", False))
+    if json_mode:
+        emit_result(_as_json_payload(), json_mode=True)
+    else:
+        emit_result(_TEXT, json_mode=False)
+    return 0
+
+
+def register(sub: argparse._SubParsersAction) -> None:
+    p = sub.add_parser(
+        "learn",
+        help="Print a structured self-teaching prompt for agent consumers.",
+    )
+    p.add_argument("--json", action="store_true", help="Emit structured JSON.")
+    p.set_defaults(func=cmd_learn)

katvan/cli/_errors.py

@@ -0,0 +1,44 @@
+"""KatvanError and exit-code policy.
+
+Every failure inside katvan raises :class:`KatvanError`. The top-level
+``main()`` catches it, formats via :mod:`katvan.cli._output`, and exits with
+:attr:`KatvanError.code`. This guarantees:
+
+* no Python traceback leaks to stderr (agent-first error rubric);
+* every error has a structured shape ``{code, message, remediation}``;
+* the exit-code policy is centralised in one place.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+# Exit-code policy. Documented in ``katvan learn`` output.
+# 0      = success
+# 1      = user-input error (bad flag, missing required arg, unknown path)
+# 2      = environment / setup error (tool not installed, file unreadable)
+# 3      = internal/unexpected error (a bug in katvan)
+# 4+     = reserved for future categorisation
+EXIT_SUCCESS = 0
+EXIT_USER_ERROR = 1
+EXIT_ENV_ERROR = 2
+EXIT_INTERNAL_ERROR = 3
+
+
+@dataclass
+class KatvanError(Exception):
+    """Structured error raised within katvan; carries a remediation hint for agents."""
+
+    code: int
+    message: str
+    remediation: str = ""
+
+    def __post_init__(self) -> None:
+        super().__init__(self.message)
+
+    def to_dict(self) -> dict[str, object]:
+        return {
+            "code": self.code,
+            "message": self.message,
+            "remediation": self.remediation,
+        }

katvan/cli/_output.py

@@ -0,0 +1,58 @@
+"""stdout / stderr helpers with a strict split.
+
+Rule: **results go to stdout, diagnostics and errors go to stderr.** Agents
+parsing katvan output can rely on this invariant. JSON mode routes structured
+payloads to the same streams — never mixes them.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from typing import Any, TextIO
+
+from katvan.cli._errors import KatvanError
+
+
+def emit_result(data: Any, *, json_mode: bool, stream: TextIO | None = None) -> None:
+    """Write a command result.
+
+    Text mode: ``data`` is treated as a string (or stringified) and a trailing
+    newline is ensured. JSON mode: ``data`` is JSON-dumped with a trailing
+    newline. Default stream is stdout.
+    """
+    s = stream if stream is not None else sys.stdout
+    if json_mode:
+        json.dump(data, s, ensure_ascii=False)
+        s.write("\n")
+        return
+    text = data if isinstance(data, str) else str(data)
+    s.write(text)
+    if not text.endswith("\n"):
+        s.write("\n")
+
+
+def emit_error(err: KatvanError, *, json_mode: bool, stream: TextIO | None = None) -> None:
+    """Write a :class:`KatvanError` to stderr.
+
+    Text mode renders as two lines when a remediation is present::
+
+        error: <message>
+        hint: <remediation>
+
+    The ``hint:`` prefix is what the error-propagation rubric bundle looks for.
+    """
+    s = stream if stream is not None else sys.stderr
+    if json_mode:
+        json.dump(err.to_dict(), s, ensure_ascii=False)
+        s.write("\n")
+        return
+    s.write(f"error: {err.message}\n")
+    if err.remediation:
+        s.write(f"hint: {err.remediation}\n")
+
+
+def emit_diagnostic(message: str, *, stream: TextIO | None = None) -> None:
+    """Write a human diagnostic (progress, summary) to stderr."""
+    s = stream if stream is not None else sys.stderr
+    s.write(message if message.endswith("\n") else message + "\n")

katvan/explain/__init__.py

@@ -0,0 +1,27 @@
+"""Explain catalog — markdown keyed by command-path tuples.
+
+See :mod:`katvan.explain.catalog` for the string bodies and :func:`resolve`
+for lookup. Every noun/verb in the CLI should have a catalog entry.
+"""
+
+from __future__ import annotations
+
+from katvan.cli._errors import EXIT_USER_ERROR, KatvanError
+from katvan.explain.catalog import ENTRIES
+
+
+def resolve(path: tuple[str, ...]) -> str:
+    """Return the markdown body for ``path`` or raise :class:`KatvanError`."""
+    if path in ENTRIES:
+        return ENTRIES[path]
+    display = " ".join(path) if path else "<root>"
+    raise KatvanError(
+        code=EXIT_USER_ERROR,
+        message=f"no explain entry for: {display}",
+        remediation="list known entries with: katvan explain katvan",
+    )
+
+
+def known_paths() -> list[tuple[str, ...]]:
+    """Return every catalog path (used by tests)."""
+    return list(ENTRIES.keys())

katvan/explain/catalog.py

@@ -0,0 +1,104 @@
+"""Markdown catalog for ``katvan explain <path>``.
+
+Each entry is verbatim markdown. Keys are command-path tuples. The empty
+tuple and ``("katvan",)`` both resolve to the root entry (aliased).
+
+Keep bodies self-contained — an agent reading a single entry should get
+enough context without chaining reads.
+"""
+
+from __future__ import annotations
+
+_ROOT = """\
+# katvan
+
+katvan maintains the docs of sibling AgentCulture repos under one roof on
+the culture.dev Jekyll site. It surveys which siblings are synced and
+fresh, pulls their raw-markdown `docs/` trees into `site/docs/<repo>/` with
+Jekyll frontmatter injected, and diagnoses doc defects. It is the
+`librarian` skill's logic, migrating into a real installable CLI.
+
+## Verbs
+
+- `katvan learn` — structured self-teaching prompt.
+- `katvan explain <path>` — markdown docs for any noun/verb.
+
+The docs verbs — `overview`, `pull`, and `doctor` — land in a later
+release, ported from the librarian skill.
+
+## Universal verb tier (agent-first)
+
+katvan exposes the universal agent-first verbs:
+
+- `learn` — what is this tool?
+- `explain <path>` — what does this command do?
+
+## Exit-code policy
+
+- `0` success
+- `1` user-input error (bad flag, bad path, missing arg)
+- `2` environment / setup error (registry not found, unreadable file)
+- `3+` reserved
+
+## See also
+
+- `katvan explain learn`
+- `katvan explain explain`
+"""
+
+_LEARN = """\
+# katvan learn
+
+Prints a structured self-teaching prompt covering katvan's purpose, command
+map, exit-code policy, `--json` support, and `explain` pointer.
+
+## Usage
+
+    katvan learn
+    katvan learn --json
+
+In JSON mode, emits
+`{"tool", "version", "purpose", "commands", "coming_soon", "exit_codes",
+"json_support", "explain_pointer"}` to stdout.
+
+## Rubric role
+
+`learn` is the learnability bundle of the agent-first rubric. Any CLI that
+passes it prints ≥200 characters and mentions purpose, commands, exit
+codes, `--json`, and `explain`.
+"""
+
+_EXPLAIN = """\
+# katvan explain <path>
+
+Prints markdown documentation for any noun/verb path. Unlike `--help`
+(terse, positional), `explain` is global and addressable by path.
+
+## Usage
+
+    katvan explain katvan
+    katvan explain learn
+    katvan explain explain --json
+
+In text mode emits the markdown to stdout. In JSON mode emits
+`{"path": [...], "markdown": "..."}` to stdout.
+
+## Path resolution
+
+Paths are shell-tokenised: `katvan explain learn` resolves to the catalog
+entry `("learn",)`. Unknown paths exit `1` with a `hint:` pointing at
+`katvan explain katvan` for the top-level map.
+
+## Rubric role
+
+`explain` is the explain bundle of the agent-first rubric: every registered
+noun must resolve, and bad paths must exit non-zero with remediation.
+"""
+
+
+ENTRIES: dict[tuple[str, ...], str] = {
+    (): _ROOT,
+    ("katvan",): _ROOT,
+    ("learn",): _LEARN,
+    ("explain",): _EXPLAIN,
+}

katvan/frontmatter.py

@@ -0,0 +1,233 @@
+"""Inject Jekyll frontmatter into a pulled sibling-repo doc.
+
+Ported near-verbatim from the librarian skill's ``_frontmatter.py``. katvan's
+``pull`` verb (landing in a later release) pipes every ``.md`` file from a
+sibling repo's ``docs/`` tree through this module before writing it under
+``site/docs/<repo>/``. Sibling docs are raw markdown — most have no
+frontmatter at all — but every page on the culture.dev multi-site build
+needs at minimum a ``sites:`` key.
+
+Logic
+-----
+* Parse an existing ``---\\n...\\n---`` frontmatter block if present.
+  Minimal hand-rolled line-oriented parser — stdlib only, NO PyYAML.
+* Merge in defaults ONLY for keys that are absent (never clobber):
+
+  - ``sites:``      → ``[culture]``
+  - ``title:``      → derived from the first ``# H1`` in the body; omitted
+    if there is no H1 (``doctor`` flags this as ``no-h1``)
+  - ``permalink:``  → ``/<repo>/<rel-path sans .md>/`` (always trailing slash)
+  - ``nav_order:``  → ``N`` if the filename has a numeric prefix like
+    ``01-foo.md``, else omitted
+
+* Emit ``---\\n<merged frontmatter>\\n---\\n<original body>``. The body is
+  preserved byte-for-byte.
+
+The core is exposed as :func:`inject` so callers (the future ``pull`` verb)
+can use it directly as a library function. :func:`main` keeps the
+stdin→stdout CLI behaviour so ``python -m katvan.frontmatter`` still works.
+"""
+
+from __future__ import annotations
+
+import argparse
+import re
+import sys
+from typing import List
+
+# Keys we emit in a stable order so output is deterministic and reviewable.
+_KEY_ORDER = ["title", "sites", "permalink", "nav_order"]
+
+
+def split_frontmatter(text, rel_path=None):
+    """Return ``(frontmatter_lines, body, warning)``.
+
+    ``frontmatter_lines`` is the list of raw lines between the ``---`` fences
+    (empty list if there is no frontmatter block). ``body`` is everything
+    after the closing fence, byte-for-byte (or the whole input if there was
+    no block). ``warning`` is ``None`` normally, or a human-readable string
+    when a malformed opener (no closing fence) was detected — callers may
+    surface it however they like; :func:`main` writes it to stderr to
+    preserve the original script's behaviour.
+    """
+    # A frontmatter block must start on the very first line with `---`.
+    if not text.startswith("---\n") and text != "---\n" and not text.startswith("---\r\n"):
+        return [], text, None
+
+    lines = text.split("\n")
+    # lines[0] is the opening `---`. Find the closing fence.
+    for idx in range(1, len(lines)):
+        if lines[idx].strip() == "---":
+            fm_lines = lines[1:idx]
+            # Body is everything after the closing fence. Slice it out of
+            # the original `text` by string offset rather than rejoining
+            # the split lines — rejoining would normalize CRLF to LF and
+            # break the "byte-for-byte" guarantee. `lines[:idx+1]` is the
+            # opening fence + frontmatter + closing fence; it was produced
+            # by splitting on "\n", so re-joining on "\n" and adding back
+            # the one trailing "\n" reconstructs the exact prefix length.
+            prefix = "\n".join(lines[: idx + 1]) + "\n"
+            body = text[len(prefix) :]
+            return fm_lines, body, None
+    # Opener with no closing fence — malformed. Surface a warning so the
+    # operator sees it (otherwise the malformed text would silently be
+    # treated as body and then re-wrapped in a fresh block, duplicating
+    # it), and treat the whole input as body.
+    where = rel_path if rel_path else "<stdin>"
+    warning = (
+        "katvan.frontmatter: warning: {}: frontmatter opener with no closing "
+        "fence — treating whole file as body".format(where)
+    )
+    return [], text, warning
+
+
+def parse_frontmatter_keys(fm_lines):
+    """Return the set of top-level keys present in the frontmatter block.
+
+    We only need to know which keys EXIST (so we never clobber them), not
+    their values — so this is a deliberately shallow parse: a line that
+    starts in column 0 with ``key:`` registers ``key``. Nested/list lines
+    (indented, or starting with ``-``) are ignored.
+    """
+    keys = set()
+    for line in fm_lines:
+        if not line or line[0] in (" ", "\t", "-", "#"):
+            continue
+        m = re.match(r"^([A-Za-z0-9_-]+):", line)
+        if m:
+            keys.add(m.group(1))
+    return keys
+
+
+def derive_title(body):
+    """First ``# H1`` in the body, leading ``# `` stripped. None if absent.
+
+    Pure-Python, no regex (a lazy ``(.+?)\\s*$`` regex here is ReDoS-prone —
+    SonarCloud ``python:S5852``). A line is an H1 iff it starts with ``#``,
+    the character right after the ``#`` is whitespace, and there is non-empty
+    content once stripped. ``## Foo`` and ``#Foo`` therefore do not match.
+    """
+    for line in body.split("\n"):
+        if not line.startswith("#"):
+            continue
+        # The char right after the leading `#` must be whitespace.
+        after = line[1:2]
+        if not after or not after.isspace():
+            continue
+        title = line[1:].strip()
+        if title:
+            return title
+    return None
+
+
+def derive_nav_order(rel_path):
+    """N if the filename has a numeric prefix like ``01-foo.md``, else None.
+
+    Pure-Python, no regex (``0*(\\d+)`` has overlapping character classes and
+    is ReDoS-prone — SonarCloud ``python:S5852``). Take the leading run of
+    ASCII digits from the filename; it counts only if immediately followed by
+    ``-`` or ``_``. ``int()`` handles leading zeros (``007`` -> ``7``).
+    """
+    filename = rel_path.rsplit("/", 1)[-1]
+    i = 0
+    while i < len(filename) and filename[i] in "0123456789":
+        i += 1
+    if i == 0 or i >= len(filename) or filename[i] not in "-_":
+        return None
+    return int(filename[:i])
+
+
+def build_permalink(repo, rel_path):
+    """``/<repo>/<rel-path sans .md>/`` — always a trailing slash."""
+    stem = rel_path
+    if stem.endswith(".md"):
+        stem = stem[:-3]
+    stem = stem.strip("/")
+    return f"/{repo}/{stem}/"
+
+
+def render_value(key, value):
+    """Render a single frontmatter line for an injected default."""
+    if key == "sites":
+        # value is a list of site ids.
+        inner = ", ".join(value)
+        return f"sites: [{inner}]"
+    if key == "nav_order":
+        return f"nav_order: {value}"
+    # title / permalink: scalar. Quote titles that could confuse the parser.
+    if key == "title":
+        if re.search(r"[:#\[\]{}]", str(value)) or str(value) != str(value).strip():
+            return 'title: "{}"'.format(str(value).replace('"', '\\"'))
+        return f"title: {value}"
+    return f"{key}: {value}"
+
+
+def inject(text: str, repo: str, rel_path: str) -> tuple[str, List[str]]:
+    """Inject Jekyll frontmatter defaults into ``text``.
+
+    Returns ``(output, warnings)`` — ``output`` is the rewritten document
+    (``---\\n<merged frontmatter>\\n---\\n<body>``), and ``warnings`` is a
+    list of human-readable warning strings (empty when nothing was amiss; a
+    malformed frontmatter opener produces one entry).
+
+    This is the core of the module, callable as a plain library function.
+    The merge is non-clobbering: an existing key is never overwritten, and
+    the original body is preserved byte-for-byte.
+    """
+    warnings: List[str] = []
+    fm_lines, body, warning = split_frontmatter(text, rel_path)
+    if warning:
+        warnings.append(warning)
+    existing_keys = parse_frontmatter_keys(fm_lines)
+
+    # Compute the defaults we would inject.
+    injected = {}
+    if "sites" not in existing_keys:
+        injected["sites"] = ["culture"]
+    if "title" not in existing_keys:
+        title = derive_title(body)
+        if title is not None:
+            injected["title"] = title
+        # else: omit — doctor will flag `no-h1`.
+    if "permalink" not in existing_keys:
+        injected["permalink"] = build_permalink(repo, rel_path)
+    if "nav_order" not in existing_keys:
+        nav = derive_nav_order(rel_path)
+        if nav is not None:
+            injected["nav_order"] = nav
+
+    # Assemble the merged frontmatter: existing lines verbatim, then the
+    # injected defaults in stable key order.
+    merged = list(fm_lines)
+    for key in _KEY_ORDER:
+        if key in injected:
+            merged.append(render_value(key, injected[key]))
+
+    out = "---\n" + "\n".join(merged) + "\n---\n" + body
+    return out, warnings
+
+
+def main(argv=None):
+    """stdin → stdout CLI shim, preserving ``_frontmatter.py``'s behaviour."""
+    parser = argparse.ArgumentParser(
+        prog="katvan.frontmatter",
+        description="Inject Jekyll frontmatter into a pulled sibling-repo doc.",
+    )
+    parser.add_argument("--repo", required=True, help="sibling repo id, e.g. ghafi")
+    parser.add_argument(
+        "--rel-path",
+        required=True,
+        help="path of the file within the sibling's docs/ dir, e.g. guides/intro.md",
+    )
+    args = parser.parse_args(argv)
+
+    text = sys.stdin.read()
+    out, warnings = inject(text, args.repo, args.rel_path)
+    for warning in warnings:
+        sys.stderr.write(warning + "\n")
+    sys.stdout.write(out)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

katvan/repos.py

@@ -0,0 +1,240 @@
+"""Sibling-repo registry — ported from the librarian skill's ``_repos.sh``.
+
+Parses ``site/_data/agentculture_repos.yml`` (the sibling-repo registry that
+drives katvan's docs verbs) and exposes lookup helpers the overview / pull /
+doctor verbs build on.
+
+Public surface
+--------------
+- :func:`registry_path` — absolute path to the registry YAML.
+- :func:`repos` — iterate ``(id, docs_mode, local_path)`` per registry entry.
+- :func:`classify` — the ``docs_mode`` for one repo id (``unknown`` if absent).
+- :func:`local_path` — the local checkout path for one repo id (``""`` if not
+  checked out).
+- :func:`set_siblings_root` / :func:`siblings_root` — override / read where
+  sibling repos are expected to be checked out locally.
+
+YAML parsing is **stdlib only** — a minimal line-oriented parser, matching
+the hand-rolled fallback the bash helper used. PyYAML is *not* a dependency.
+
+Path resolution differs deliberately from the bash original: ``_repos.sh``
+hardcoded the repo root and ``/home/spark/git``. This port walks up from the
+current working directory to find the repo root, and reads the siblings root
+from ``$KATVAN_SIBLINGS_ROOT`` (default: the parent of the discovered repo
+root). Callers may also override it programmatically via
+:func:`set_siblings_root` — PR 2's verbs thread a ``--siblings-root`` flag
+through this way.
+"""
+
+from __future__ import annotations
+
+import argparse
+import functools
+import os
+import sys
+from pathlib import Path
+from typing import Iterator
+
+from katvan.cli._errors import EXIT_ENV_ERROR, EXIT_USER_ERROR, KatvanError
+
+# Relative location of the registry within a katvan checkout.
+_REGISTRY_REL = Path("site/_data/agentculture_repos.yml")
+
+# Programmatic override for the siblings root. ``None`` means "not set" —
+# fall back to ``$KATVAN_SIBLINGS_ROOT`` then the repo root's parent.
+_siblings_root_override: Path | None = None
+
+
+def set_siblings_root(path: str | os.PathLike[str] | None) -> None:
+    """Override where sibling repos are expected to be checked out locally.
+
+    Pass ``None`` to clear the override and fall back to
+    ``$KATVAN_SIBLINGS_ROOT`` / the repo root's parent. PR 2's verbs call
+    this to honour a ``--siblings-root`` flag.
+    """
+    global _siblings_root_override
+    _siblings_root_override = Path(path) if path is not None else None
+
+
+# Memoization note: ``_find_repo_root`` and ``_parse_registry`` are wrapped
+# with ``functools.lru_cache`` — the repo root and the registry contents are
+# stable for the life of a process, and PR 2's verbs loop ``classify()`` over
+# every repo, so without caching that would be O(n^2) file reads. The
+# siblings-root (``siblings_root()`` / ``local_path()`` / ``set_siblings_root()``)
+# is deliberately NOT cached: it is intentionally mutable at runtime, and
+# nothing the caches hold depends on it, so ``set_siblings_root()`` stays
+# effective even after the registry/root have been cached.
+@functools.lru_cache(maxsize=None)
+def _find_repo_root(start: Path | None = None) -> Path:
+    """Walk up from ``start`` (default CWD) to a dir containing the registry."""
+    here = (start or Path.cwd()).resolve()
+    for candidate in (here, *here.parents):
+        if (candidate / _REGISTRY_REL).is_file():
+            return candidate
+    raise KatvanError(
+        code=EXIT_ENV_ERROR,
+        message=(f"could not find {_REGISTRY_REL} in any parent of {here}"),
+        remediation="run katvan from within a katvan checkout (the repo with site/)",
+    )
+
+
+def registry_path() -> Path:
+    """Return the absolute path to ``site/_data/agentculture_repos.yml``.
+
+    Raises :class:`KatvanError` (exit 2, environment error) if no katvan
+    checkout is found by walking up from the current working directory.
+    """
+    return _find_repo_root() / _REGISTRY_REL
+
+
+def siblings_root() -> Path:
+    """Return the directory where sibling repos are expected locally.
+
+    Precedence: explicit :func:`set_siblings_root` override >
+    ``$KATVAN_SIBLINGS_ROOT`` > the parent directory of the discovered repo
+    root.
+    """
+    if _siblings_root_override is not None:
+        return _siblings_root_override
+    env = os.environ.get("KATVAN_SIBLINGS_ROOT")
+    if env:
+        return Path(env)
+    return _find_repo_root().parent
+
+
+@functools.lru_cache(maxsize=None)
+def _parse_registry(path: Path) -> tuple[tuple[str, str], ...]:
+    """Return ``(id, docs_mode)`` for every registry entry.
+
+    Hand-rolled line-oriented parse — stdlib only, no PyYAML. Mirrors the
+    fallback parser in ``_repos.sh``: a ``- id:`` line opens an entry, a
+    following column-0 ``docs_mode:`` line sets its mode (default ``skip``).
+
+    Memoized on ``path`` — see the note above :func:`_find_repo_root`. The
+    result is a tuple (not a list) so it is hashable and safe to cache.
+
+    Raises :class:`KatvanError` if the file has non-comment content but the
+    parser still yields zero entries — a parse failure (e.g. block-style
+    YAML) that would otherwise masquerade as a legitimately empty registry.
+    A file with only comments / blank lines yields zero entries without error.
+    """
+    try:
+        raw = path.read_text(encoding="utf-8")
+    except OSError as err:
+        raise KatvanError(
+            code=EXIT_ENV_ERROR,
+            message=f"registry not readable: {path}: {err}",
+            remediation="check the file exists and is readable",
+        ) from err
+
+    entries: list[tuple[str, str]] = []
+    has_content = False
+    cur: list[str] | None = None
+    for line in raw.splitlines():
+        stripped = line.strip()
+        if not stripped or stripped.startswith("#"):
+            continue
+        has_content = True
+        if stripped.startswith("- id:"):
+            if cur is not None:
+                entries.append((cur[0], cur[1]))
+            rid = stripped.split(":", 1)[1].strip().strip("'\"")
+            cur = [rid, "skip"]
+        elif cur is not None and stripped.startswith("docs_mode:"):
+            cur[1] = stripped.split(":", 1)[1].strip().strip("'\"")
+    if cur is not None:
+        entries.append((cur[0], cur[1]))
+
+    if not entries and has_content:
+        raise KatvanError(
+            code=EXIT_ENV_ERROR,
+            message=(
+                f"registry parsed zero entries from {path} — expected '- id:' "
+                "entries; the file may be malformed or in an unsupported YAML style"
+            ),
+            remediation="check the registry uses inline '- id: <name>' entry openers",
+        )
+    return tuple(entries)
+
+
+def local_path(repo_id: str) -> str:
+    """Return the local checkout path for ``repo_id``, or ``""`` if absent.
+
+    The candidate is ``<siblings_root>/<repo_id>``; it is returned only when
+    that directory actually exists.
+    """
+    candidate = siblings_root() / repo_id
+    return str(candidate) if candidate.is_dir() else ""
+
+
+def repos() -> Iterator[tuple[str, str, str]]:
+    """Yield ``(id, docs_mode, local_path)`` for every registry entry.
+
+    ``local_path`` is ``<siblings_root>/<id>`` when that directory exists,
+    else the empty string — matching ``_repos.sh``'s ``librarian_repos``.
+    """
+    for rid, mode in _parse_registry(registry_path()):
+        if not rid:
+            continue
+        yield rid, mode, local_path(rid)
+
+
+def classify(repo_id: str) -> str:
+    """Return the ``docs_mode`` for ``repo_id``.
+
+    One of ``pull`` / ``self-published`` / ``skip`` for a registered repo, or
+    ``"unknown"`` if the id is not in the registry. (The bash original also
+    signalled this via a non-zero return code; the Python port surfaces it
+    purely through the ``"unknown"`` sentinel.)
+    """
+    for rid, mode in _parse_registry(registry_path()):
+        if rid == repo_id:
+            return mode
+    return "unknown"
+
+
+def main(argv: list[str] | None = None) -> int:
+    """Tiny CLI shim so ``python -m katvan.repos`` is inspectable.
+
+    With no args, prints the ``id<TAB>docs_mode<TAB>local_path`` table — the
+    same shape ``_repos.sh``'s ``librarian_repos`` emitted.
+    """
+    parser = argparse.ArgumentParser(
+        prog="katvan.repos",
+        description="Inspect the AgentCulture sibling-repo registry.",
+    )
+    parser.add_argument(
+        "--registry-path",
+        action="store_true",
+        help="Print the absolute registry path and exit.",
+    )
+    parser.add_argument(
+        "--classify",
+        metavar="REPO_ID",
+        help="Print the docs_mode for REPO_ID and exit.",
+    )
+    args = parser.parse_args(argv)
+
+    try:
+        if args.registry_path:
+            print(registry_path())
+            return 0
+        if args.classify:
+            mode = classify(args.classify)
+            print(mode)
+            # The library ``classify()`` returns the ``"unknown"`` sentinel,
+            # but the CLI shim mirrors ``_repos.sh``'s ``librarian_classify``,
+            # which exited non-zero for an unregistered repo id.
+            return EXIT_USER_ERROR if mode == "unknown" else 0
+        for rid, mode, path in repos():
+            print(f"{rid}\t{mode}\t{path}")
+    except KatvanError as err:
+        sys.stderr.write(f"error: {err.message}\n")
+        if err.remediation:
+            sys.stderr.write(f"hint: {err.remediation}\n")
+        return err.code
+    return 0
+
+
+if __name__ == "__main__":  # pragma: no cover
+    sys.exit(main())

katvan-0.1.0.dist-info/METADATA

@@ -0,0 +1,63 @@
+Metadata-Version: 2.4
+Name: katvan
+Version: 0.1.0
+Summary: Maintain sibling-repo docs under one roof on the culture.dev site.
+Project-URL: Homepage, https://github.com/agentculture/katvan
+Project-URL: Issues, https://github.com/agentculture/katvan/issues
+Author: AgentCulture
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Documentation
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+
+# katvan
+
+Home of the **culture.dev** documentation site, and the `katvan` CLI that
+maintains it.
+
+The Jekyll project lives under [`site/`](site/) — config, theme, data,
+assets, and the docs content tree. Repo-root [`docs/`](docs/) is
+katvan's own internal documentation (skill provenance, design specs),
+not part of the published site.
+
+## The `katvan` CLI
+
+`katvan` is a Python CLI that maintains the docs of sibling AgentCulture
+repos under one roof on the culture.dev site — surveying which siblings
+are synced and fresh, pulling their raw-markdown `docs/` trees into
+`site/docs/<repo>/` with Jekyll frontmatter injected, and diagnosing doc
+defects. It is the `librarian` skill's logic, migrating into a real
+installable CLI.
+
+```bash
+uv tool install katvan
+```
+
+Verbs available today:
+
+- `katvan learn` — structured self-teaching prompt for agent consumers
+  (supports `--json`).
+- `katvan explain <path>` — markdown docs for any noun/verb path
+  (supports `--json`).
+
+The docs verbs — `overview`, `pull`, and `doctor` — land in a later
+release, ported from the `librarian` skill.
+
+## Build the site locally
+
+```bash
+cd site
+bundle install
+bundle exec jekyll serve --config _config.base.yml,_config.culture.yml
+```
+
+CI builds the site on every PR via `.github/workflows/docs-check.yml`.
+
+Migration design and implementation plan:
+`docs/superpowers/specs/2026-05-14-culture-site-migration-design.md`
+and `docs/superpowers/plans/2026-05-14-culture-site-migration.md`.

katvan-0.1.0.dist-info/RECORD

@@ -0,0 +1,17 @@
+katvan/__init__.py,sha256=sTgcOychXlxDdNO1bXghqcE4NgqusbAr2sZ6NG-uZqU,344
+katvan/__main__.py,sha256=JPnbmd7r4F0NS9sKlaeBjm_Dkt7uoWOXc_xjr_isD28,142
+katvan/frontmatter.py,sha256=JpBNETgBxdhmpzbjLVbPlgnbqYaSU8-T8Kbep_xNsP8,9228
+katvan/repos.py,sha256=pKAMTs_dg6O3uf8Z6vYhlV82gyL4olD34QzDDOpaO9g,9316
+katvan/cli/__init__.py,sha256=x2zz5S9r0n9nrQK7pi4W4w1QXSfGta2tlqnIZfcZdG0,5139
+katvan/cli/_errors.py,sha256=7HAAM1b--20zpkNF1LyZ_8_wLvxF9GoN1oOMl2aOX28,1355
+katvan/cli/_output.py,sha256=XSzW2GALJJ6vw1lGmwX_yb-po3xvwrEiiPMW4v5EH8o,1886
+katvan/cli/_commands/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+katvan/cli/_commands/explain.py,sha256=QBS41rzi0SoyC8r3u3lHYv2UJPz-GM0_u-qGMF6lqK8,1277
+katvan/cli/_commands/learn.py,sha256=1Pgr1VdbOACVrp_WCTFeA9B178WtS7eNw4VhNYVPat4,3769
+katvan/explain/__init__.py,sha256=lsmol6CziqWtDQ42J8Cz2cXfNGVBwx2vwDf1RpB-b1c,891
+katvan/explain/catalog.py,sha256=JgCRk_ATL8VwQwjGH6ZjU2O8gvr0agInIUjR0BL7PWI,2849
+katvan-0.1.0.dist-info/METADATA,sha256=RG0O54DogUXp5csNJpaB2_cQz2FnvUIQRb9PfNM5e6w,2095
+katvan-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+katvan-0.1.0.dist-info/entry_points.txt,sha256=UrUztp0az7mAHLIxFLxUCkwh97d8JxyBmL5_tncW7ow,43
+katvan-0.1.0.dist-info/licenses/LICENSE,sha256=wCcdPywGtFXx1P8N0j0eEDINSWfSjrIsU7ds1YZl-MA,1069
+katvan-0.1.0.dist-info/RECORD,,

katvan-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

katvan-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+katvan = katvan.cli:main

katvan-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AgentCulture
+
+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.