frontmattering 0.4.2__py3-none-any.whl

frontmattering/__main__.py

@@ -0,0 +1,1263 @@
+from __future__ import annotations
+
+import argparse
+import contextlib
+import hashlib
+import importlib.util
+import zipfile
+import io
+import json
+import os
+import re
+import shutil
+import sys
+from pathlib import Path
+from typing import Any
+
+sys.dont_write_bytecode = True
+
+
+PACKAGE_ROOT = Path(__file__).resolve().parent
+_SOURCE_KERNEL_ROOT = PACKAGE_ROOT.parent
+KERNEL_ROOT = _SOURCE_KERNEL_ROOT if (_SOURCE_KERNEL_ROOT / "FRONTMATTERING_FRONTMATTER_SPEC_v0_1_5.md").exists() else PACKAGE_ROOT / "resources"
+TOOLS_DIR = KERNEL_ROOT / "tools"
+SPEC_PATH = KERNEL_ROOT / "FRONTMATTERING_FRONTMATTER_SPEC_v0_1_5.md"
+
+if str(TOOLS_DIR) not in sys.path:
+    sys.path.insert(0, str(TOOLS_DIR))
+
+from .speccompile import load_spec  # noqa: E402
+from .validator import validate_docset  # noqa: E402
+from .schema_projection import render_schema  # noqa: E402
+from .core import parse_frontmatter, split_frontmatter  # noqa: E402
+from .markdown.api import parse_markdown_text  # noqa: E402
+from .ai_instruction_risk import scan_ai_instruction_risk  # noqa: E402
+from .frontmatter_index import build_index, ensure_index_fresh, query_index, DEFAULT_INDEX  # noqa: E402
+from .authoring import init_project, new_document, PROFILES  # noqa: E402
+from .corpus_selection import SelectionResult, resolve_corpus  # noqa: E402
+from .inventory import build_inventory  # noqa: E402
+from .promotion import promote_document  # noqa: E402
+from .body_tether import update_tether  # noqa: E402
+from .harness_errors import HarnessError, InternalBugError, ToolingError  # noqa: E402
+from finding_registry import declared_finding_ids, finding_contract, guidance_for, retired_finding_info  # noqa: E402
+from kernel_reporting import (  # noqa: E402
+    render_mesh_report,
+    render_brief_report,
+    render_report,
+    validation_report,
+)
+
+
+EXIT_GO = 0
+EXIT_FINDING = 1
+EXIT_USAGE = 2
+EXIT_SELF_CHECK = 3
+EXIT_INTERNAL = 4
+
+
+class StrictArgumentParser(argparse.ArgumentParser):
+    """Argument parser with exact option names and no legacy prefix matching."""
+
+    def __init__(self, *args: Any, **kwargs: Any) -> None:
+        kwargs.setdefault("allow_abbrev", False)
+        super().__init__(*args, **kwargs)
+BRIEF_DEV_DIR_NAMES = {"archive", "distro_smoke", "fixtures", "mesh", "usecase"}
+ROUTING_TASK_FIELDS = {"routing.read_when_tags[]", "routing.skip_when_tags[]"}
+
+
+def collect_markdown_paths(inputs: list[str]) -> list[Path]:
+    """Resolve Markdown paths through the single Frontmattering v0.3 selection authority."""
+    return list(resolve_corpus(inputs).paths)
+
+
+def build_report(inputs: list[str]) -> dict[str, Any]:
+    selection = resolve_corpus(inputs)
+    paths = list(selection.paths)
+    auth = load_spec(SPEC_PATH)
+    result = validate_docset(paths, auth)
+    report = validation_report(target_paths=paths, auth=auth, result=result)
+    report["selection"] = selection.payload()
+    report["project"] = {
+        "project_file": str(selection.project_file.resolve()) if selection.project_file else None,
+        "project_schema": selection.project_schema,
+        "validation_profile": selection.validation_profile,
+    }
+    return report
+
+def brief_paths(paths: list[Path], *, include_dev: bool, inputs: list[str]) -> list[Path]:
+    if include_dev:
+        return paths
+    explicit_dev_roots = {
+        Path(raw).resolve()
+        for raw in inputs
+        if Path(raw).name in BRIEF_DEV_DIR_NAMES
+    }
+
+    def is_explicit_dev_target(path: Path) -> bool:
+        resolved = path.resolve()
+        return any(resolved == root or resolved.is_relative_to(root) for root in explicit_dev_roots)
+
+    filtered = [
+        path for path in paths
+        if is_explicit_dev_target(path) or not any(part in BRIEF_DEV_DIR_NAMES for part in path.parts)
+    ]
+    if not filtered:
+        raise ToolingError(
+            "Cold-start brief has no non-dev Markdown targets",
+            "brief target filtering",
+            "The brief command hides fixture/archive/dev-only directories by default.",
+            "Pass --include-dev or point brief at the intended authored document files.",
+            {"filtered_directories": sorted(BRIEF_DEV_DIR_NAMES)},
+            error_id="FRONTMATTERING-KERNEL-BRIEF-NO-TARGETS",
+        )
+    return filtered
+
+
+def build_brief_report(inputs: list[str], *, include_dev: bool) -> dict[str, Any]:
+    selection = resolve_corpus(inputs)
+    paths = brief_paths(list(selection.paths), include_dev=include_dev, inputs=inputs)
+    final_selection = selection.restrict(paths)
+    auth = load_spec(SPEC_PATH)
+    result = validate_docset(paths, auth)
+    report = validation_report(target_paths=paths, auth=auth, result=result)
+    report["selection"] = final_selection.payload()
+    report["project"] = {
+        "project_file": str(selection.project_file.resolve()) if selection.project_file else None,
+        "project_schema": selection.project_schema,
+        "validation_profile": selection.validation_profile,
+    }
+    return report
+
+
+def exit_for_report(report: dict[str, Any]) -> int:
+    return EXIT_GO if report.get("terminal_state") == "GO" else EXIT_FINDING
+
+
+def selected_format(args: argparse.Namespace) -> str:
+    return args.format
+
+
+def command_validate(args: argparse.Namespace) -> int:
+    try:
+        report = build_report(args.paths)
+    except ToolingError as exc:
+        print(exc, file=sys.stderr)
+        return EXIT_USAGE
+    print(render_report(report, selected_format(args)))
+    return exit_for_report(report)
+
+
+def command_mesh(args: argparse.Namespace) -> int:
+    try:
+        report = build_report(args.paths)
+    except ToolingError as exc:
+        print(exc, file=sys.stderr)
+        return EXIT_USAGE
+    print(render_mesh_report(report, selected_format(args)))
+    return exit_for_report(report)
+
+
+def command_brief(args: argparse.Namespace) -> int:
+    try:
+        report = build_brief_report(args.paths, include_dev=args.include_dev)
+        rendered = render_brief_report(report, selected_format(args), task=args.task, section=args.section)
+    except ToolingError as exc:
+        print(exc, file=sys.stderr)
+        return EXIT_USAGE
+    print(rendered)
+    return EXIT_GO
+
+
+def command_explain(args: argparse.Namespace) -> int:
+    auth = load_spec(SPEC_PATH)
+    declared = args.finding_id in declared_finding_ids(auth)
+    retired = retired_finding_info(args.finding_id)
+    payload = finding_contract(args.finding_id, auth=auth)
+    if retired is not None:
+        payload.update({
+            "finding_status": "retired",
+            "retired_in": retired["retired_in"],
+            "last_declared_in": retired["last_declared_in"],
+            "superseded_by": retired["superseded_by"],
+            "retirement_reason": retired["reason"],
+        })
+    elif not declared:
+        payload["finding_status"] = "unknown"
+    if args.format == "json":
+        print(json.dumps(payload, indent=2, sort_keys=True))
+    else:
+        print(f"# {args.finding_id}")
+        print()
+        for key in ("finding_status", "title", "class", "severity", "automation_class", "why"):
+            print(f"- {key}: {payload.get(key)}")
+        print("- deterministic_repairs:")
+        for item in payload.get("deterministic_repairs") or []:
+            print(f"  - {item}")
+        print("- judgment_required:")
+        for item in payload.get("judgment_required") or []:
+            print(f"  - {item}")
+        print()
+        print("Claim boundary:")
+        for item in payload.get("does_not_verify") or []:
+            print(f"- does_not_verify: {item}")
+    return EXIT_GO if declared else EXIT_FINDING
+
+def _tether_status_rows(paths: list[Path]) -> list[dict[str, Any]]:
+    auth = load_spec(SPEC_PATH)
+    result = validate_docset(paths, auth)
+    rows = []
+    for path, per_doc in sorted((result.get("per_document") or {}).items()):
+        fm = per_doc.get("fm") or {}
+        adc = fm.get("ai_document_contract", {}) if isinstance(fm, dict) else {}
+        status = per_doc.get("body_tether") or {}
+        rows.append({
+            "path": path,
+            "document_id": adc.get("document_id"),
+            "freshness": status.get("freshness") or "UNTETHERED",
+            "summary_trust": status.get("summary_trust") or "orientation_only",
+            "reasons": status.get("reasons") or [],
+            "body_sha256_current": status.get("body_sha256_current"),
+            "body_sha256_declared": status.get("body_sha256_declared"),
+            "tethered_fields_sha256_current": status.get("tethered_fields_sha256_current"),
+            "tethered_fields_sha256_declared": status.get("tethered_fields_sha256_declared"),
+        })
+    return rows
+
+
+def command_tether_check(args: argparse.Namespace) -> int:
+    try:
+        paths = collect_markdown_paths(args.paths)
+    except ToolingError as exc:
+        print(exc, file=sys.stderr)
+        return EXIT_USAGE
+    rows = _tether_status_rows(paths)
+    payload = {
+        "schema_version": "frontmattering_tether_check/v0_1",
+        "document_count": len(rows),
+        "stale_count": sum(1 for row in rows if row["freshness"] == "STALE"),
+        "untethered_count": sum(1 for row in rows if row["freshness"] == "UNTETHERED"),
+        "fresh_count": sum(1 for row in rows if row["freshness"] == "FRESH"),
+        "rows": rows,
+        "claim_boundary": {
+            "verifies": ["Body/frontmatter tether freshness under the current validator semantics."],
+            "does_not_verify": ["Semantic correctness of summaries or external approval."],
+        },
+    }
+    if args.format == "json":
+        print(json.dumps(payload, indent=2, sort_keys=True, default=str))
+    else:
+        print("# Frontmattering tether check")
+        print(f"fresh={payload['fresh_count']} stale={payload['stale_count']} untethered={payload['untethered_count']}")
+        for row in rows:
+            reasons = ";".join(row.get("reasons") or []) or "none"
+            print(f"- {row['freshness']} {row.get('document_id') or '?'} {row['path']} summary_trust={row['summary_trust']} reasons={reasons}")
+    return EXIT_FINDING if payload["stale_count"] else EXIT_GO
+
+
+def command_tether_update(args: argparse.Namespace) -> int:
+    try:
+        paths = collect_markdown_paths(args.paths)
+    except ToolingError as exc:
+        print(exc, file=sys.stderr)
+        return EXIT_USAGE
+    updated = []
+    skipped = []
+    failed = []
+    for path in paths:
+        try:
+            if update_tether(path, add=args.add, canonical_fields=load_spec(SPEC_PATH).body_tether_canonical_trust_fields):
+                updated.append(str(path))
+            else:
+                skipped.append(str(path))
+        except (OSError, ValueError, yaml.YAMLError) as exc:
+            failed.append({"path": str(path), "error": str(exc)})
+    payload = {
+        "schema_version": "frontmattering_tether_update/v0_1",
+        "updated_count": len(updated),
+        "skipped_count": len(skipped),
+        "failed_count": len(failed),
+        "updated_paths": updated,
+        "skipped_paths": skipped,
+        "failures": failed,
+        "claim_boundary": {
+            "verifies": ["body_tether digest fields were recomputed for reported updated files."],
+            "does_not_verify": ["Semantic correctness of summaries or external approval."],
+        },
+    }
+    if args.format == "json":
+        print(json.dumps(payload, indent=2, sort_keys=True, default=str))
+    else:
+        print("# Frontmattering tether update")
+        print(f"updated={len(updated)} skipped={len(skipped)} failed={len(failed)}")
+        for path in updated:
+            print(f"- updated {path}")
+        for path in skipped:
+            print(f"- skipped {path}")
+        for item in failed:
+            print(f"- failed {item['path']}: {item['error']}")
+    return EXIT_FINDING if failed else EXIT_GO
+
+def run_doctor_step(name: str, argv: list[str], *, cwd: Path) -> dict[str, Any]:
+    """Execute a shipped Python check in-process with isolated argv and output.
+
+    Doctor used to launch one subprocess per check. In constrained agent and CI
+    environments, repeated child creation could stall after several successful
+    checks. Loading each shipped script from its own path preserves that script's
+    ROOT semantics while giving doctor one deterministic process boundary.
+    """
+    if len(argv) < 2:
+        return {
+            "name": name,
+            "argv": argv,
+            "exit_code": 2,
+            "status": "FAIL",
+            "output": "Doctor step is missing a Python script path.",
+            "verifies": [],
+            "does_not_verify": ["The malformed doctor step was not executed."],
+        }
+    script = Path(argv[1])
+    if not script.is_absolute():
+        script = cwd / script
+    module_name = "_frontmattering_doctor_" + hashlib.sha256(
+        f"{name}:{script}".encode("utf-8")
+    ).hexdigest()[:16]
+    stdout = io.StringIO()
+    stderr = io.StringIO()
+    old_argv = list(sys.argv)
+    old_cwd = Path.cwd()
+    exit_code = 0
+    try:
+        os.chdir(cwd)
+        sys.argv = [str(script), *argv[2:]]
+        spec = importlib.util.spec_from_file_location(module_name, script)
+        if spec is None or spec.loader is None:
+            raise InternalBugError(
+                "Cannot load doctor check",
+                where="frontmattering.__main__.run_doctor_step",
+                context={"name": name, "script": str(script)},
+            )
+        module = importlib.util.module_from_spec(spec)
+        with contextlib.redirect_stdout(stdout), contextlib.redirect_stderr(stderr):
+            try:
+                spec.loader.exec_module(module)
+                main_fn = getattr(module, "main", None)
+                if callable(main_fn):
+                    result = main_fn()
+                    exit_code = 0 if result is None else int(result)
+            except SystemExit as exc:
+                value = exc.code
+                exit_code = value if isinstance(value, int) else (0 if value is None else 1)
+            except (HarnessError, OSError, ValueError, TypeError, AssertionError, ImportError, SyntaxError) as exc:
+                exit_code = 1
+                print(f"{type(exc).__name__}: {exc}", file=stderr)
+    finally:
+        sys.argv = old_argv
+        os.chdir(old_cwd)
+    output = "\n".join(part for part in [stdout.getvalue().strip(), stderr.getvalue().strip()] if part)
+    return {
+        "name": name,
+        "argv": argv,
+        "exit_code": exit_code,
+        "status": "PASS" if exit_code == 0 else "FAIL",
+        "output": output,
+        "verifies": [f"The named deterministic check {name} executed with the recorded exit code."],
+        "does_not_verify": ["Semantic adequacy, external adoption, release approval, or production readiness."],
+    }
+
+
+def command_doctor(args: argparse.Namespace) -> int:
+    python = sys.executable
+    root = KERNEL_ROOT.parents[1]
+    rel = lambda path: str(path.relative_to(root))
+    steps = [
+        run_doctor_step(
+            "python_syntax",
+            [python, rel(KERNEL_ROOT / "tools" / "check_python_syntax.py")],
+            cwd=root,
+        ),
+        run_doctor_step(
+            "report_quality",
+            [python, rel(KERNEL_ROOT / "tools" / "check_report_quality.py")],
+            cwd=root,
+        ),
+        run_doctor_step(
+            "exception_taxonomy",
+            [python, rel(KERNEL_ROOT / "tools" / "check_kernel_exception_taxonomy.py")],
+            cwd=root,
+        ),
+        run_doctor_step(
+            "ai_index_current",
+            [python, rel(KERNEL_ROOT / "tools" / "generate_ai_index.py"), "--check"],
+            cwd=root,
+        ),
+        run_doctor_step(
+            "frontmatter_schema_current",
+            [python, rel(KERNEL_ROOT / "tools" / "generate_frontmatter_schema.py"), "--check"],
+            cwd=root,
+        ),
+        run_doctor_step(
+            "projection_consistency",
+            [python, rel(KERNEL_ROOT / "tools" / "check_projection_consistency.py")],
+            cwd=root,
+        ),
+        run_doctor_step(
+            "markdown_parser_adoption",
+            [python, rel(KERNEL_ROOT / "tools" / "check_markdown_parser_adoption.py")],
+            cwd=root,
+        ),
+        run_doctor_step(
+            "frontmatter_sqlite_index",
+            [python, rel(KERNEL_ROOT / "tools" / "check_frontmatter_sqlite_index.py")],
+            cwd=root,
+        ),
+        run_doctor_step(
+            "kernel_verifier",
+            [python, rel(KERNEL_ROOT / "tools" / "verify_kernel.py")],
+            cwd=root,
+        ),
+        run_doctor_step(
+            "brief_smoke",
+            [
+                python,
+                rel(KERNEL_ROOT / "tools" / "frontmattering_cli.py"),
+                "brief",
+                rel(KERNEL_ROOT / "AI_START_HERE.md"),
+                rel(KERNEL_ROOT / "FRONTMATTERING_FRONTMATTER_SPEC_v0_1_5.md"),
+                "--task",
+                "frontmatter_authoring",
+                "--format",
+                "json",
+            ],
+            cwd=root,
+        ),
+        run_doctor_step(
+            "cleanliness",
+            [python, rel(KERNEL_ROOT / "tools" / "check_kernel_cleanliness.py")],
+            cwd=root,
+        ),
+    ]
+    overall = "PASS" if all(step["exit_code"] == 0 for step in steps) else "FAIL"
+    if args.format == "json":
+        print(json.dumps({"schema_version": "frontmattering_doctor/v0_3", "doctor_verdict": overall, "steps": steps, "claim_boundary": {"verifies": ["Named local checks executed."], "does_not_verify": ["Semantic adequacy, external adoption, release approval, or production readiness."]}}, indent=2, sort_keys=True))
+    else:
+        print(f"# Frontmattering kernel doctor\n\n- doctor_verdict: {overall}")
+        for step in steps:
+            print()
+            print(f"## {step['name']}")
+            print(f"- status: {step['status']}")
+            print(f"- exit_code: {step['exit_code']}")
+            if step["output"]:
+                print()
+                print("```text")
+                print(step["output"])
+                print("```")
+    return EXIT_GO if overall == "PASS" else EXIT_SELF_CHECK
+
+
+def catalog_payload(auth: Any, field: str | None) -> dict[str, Any]:
+    if field is not None:
+        entry = auth.fields.get(field)
+        if entry is None:
+            raise ToolingError(
+                "Unknown frontmatter field",
+                field,
+                "The field is not in the closed field catalog of this specification.",
+                "Run `frontmattering catalog` with no --field to list the closed vocabularies.",
+                {"field": field},
+                error_id="FRONTMATTERING-KERNEL-CATALOG-FIELD-UNKNOWN",
+            )
+        payload = {
+            "field": field,
+            "type": entry.get("type"),
+            "required_when": entry.get("required_when"),
+            "allowed_values": entry.get("allowed_values"),
+        }
+        if field in ROUTING_TASK_FIELDS:
+            built_ins = entry.get("allowed_values") or []
+            payload["allowed_values"] = None
+            payload["value_domain"] = {
+                "built_in_values": built_ins,
+                "corpus_declared_values": "Any task_tag value declared in routing.task_catalog[] by an in-scope package_router document.",
+                "router_field": "routing.task_catalog[]",
+                "scope_note": "Single-file validation of a document with corpus-local tags requires the package_router document in the same validation target.",
+            }
+        return payload
+    return {
+        "closed_root_blocks": sorted(auth.closed_root),
+        "closed_vocabularies": {
+            name: entry.get("allowed_values")
+            for name, entry in sorted(auth.fields.items())
+            if entry.get("allowed_values")
+        },
+        "role_compatibility": auth.role_compat,
+        "claim_state_compatibility": auth.claim_compat,
+    }
+
+
+def command_catalog(args: argparse.Namespace) -> int:
+    auth = load_spec(SPEC_PATH)
+    try:
+        payload = catalog_payload(auth, args.field)
+    except ToolingError as exc:
+        print(exc, file=sys.stderr)
+        return EXIT_USAGE
+
+    payload["spec_sha256"] = auth.spec_sha256
+    payload["claim_boundary"] = (
+        "Catalog projects the closed model of this specification. "
+        "It is not validation evidence and does not verify any document."
+    )
+
+    if args.format == "json":
+        print(json.dumps(payload, indent=2, sort_keys=True))
+        return EXIT_GO
+
+    print("# Frontmattering closed model catalog")
+    print()
+    print(f"- spec_sha256: {auth.spec_sha256}")
+    print()
+    if args.field:
+        print(f"## {payload['field']}")
+        print()
+        print(f"- type: {payload['type']}")
+        print(f"- required_when: {payload['required_when']}")
+        values = payload["allowed_values"]
+        if values:
+            print("- allowed_values:")
+            for value in values:
+                print(f"  - {value}")
+        else:
+            print("- allowed_values: (open - constrained by type, not by enum)")
+        if payload.get("value_domain"):
+            domain = payload["value_domain"]
+            print("- value_domain:")
+            print("  - built_in_values:")
+            for value in domain["built_in_values"]:
+                print(f"    - {value}")
+            print(f"  - corpus_declared_values: {domain['corpus_declared_values']}")
+            print(f"  - router_field: {domain['router_field']}")
+            print(f"  - scope_note: {domain['scope_note']}")
+    else:
+        print("## Closed root blocks")
+        print()
+        for block in payload["closed_root_blocks"]:
+            print(f"- {block}")
+        print()
+        print("## Closed vocabularies")
+        print()
+        for name, values in payload["closed_vocabularies"].items():
+            print(f"- {name}: {', '.join(str(v) for v in values)}")
+    print()
+    print("Claim boundary: the catalog projects the closed model only; "
+          "it is not validation evidence.")
+    return EXIT_GO
+
+
+def _task_tags_from_paths(inputs: list[str]) -> set[str]:
+    tags: set[str] = set()
+    for path in collect_markdown_paths(inputs):
+        fm, _body, findings = parse_frontmatter(path.read_text(encoding="utf-8"))
+        if fm is None or findings:
+            continue
+        routing = fm.get("routing") if isinstance(fm, dict) else None
+        if isinstance(routing, dict):
+            for tag in routing.get("task_catalog") or []:
+                if isinstance(tag, str) and tag:
+                    tags.add(tag)
+    return tags
+
+
+def command_schema(args: argparse.Namespace) -> int:
+    selection = None
+    try:
+        if args.paths:
+            selection = resolve_corpus(args.paths)
+            tags = _task_tags_from_paths([str(path) for path in selection.paths])
+        else:
+            tags = set()
+    except ToolingError as exc:
+        print(exc, file=sys.stderr)
+        return EXIT_USAGE
+    schema_payload = json.loads(render_schema(load_spec(SPEC_PATH), additional_task_tags=tags))
+    if selection is not None:
+        selection_payload = selection.payload()
+        schema_payload["selection"] = selection_payload
+        schema_payload["x-frontmattering-selection"] = selection_payload
+    rendered = json.dumps(schema_payload, indent=2, sort_keys=True) + "\n"
+    if args.vscode:
+        schema_path = args.output or ".frontmattering/generated/FRONTMATTERING_FRONTMATTER_SCHEMA.schema.json"
+        payload = {"yaml.schemas": {schema_path: ["docs/**/*.md"]}}
+        print(json.dumps(payload, indent=2, sort_keys=True))
+        return EXIT_GO
+    if args.check:
+        target = Path(args.check)
+        if not target.exists() or target.read_text(encoding="utf-8") != rendered:
+            print(ToolingError("Generated JSON Schema is stale", str(target), "Fresh corpus-aware schema emission differs from the written projection.", f"Run: frontmattering schema {' '.join(args.paths)} --output {target}", error_id="FRONTMATTERING-SCHEMA-STALE"), file=sys.stderr)
+            return EXIT_FINDING
+        print(f"schema_check=PASS path={target}")
+        return EXIT_GO
+    if args.output:
+        target = Path(args.output)
+        target.parent.mkdir(parents=True, exist_ok=True)
+        target.write_text(rendered, encoding="utf-8")
+        print(f"schema_written={target}")
+        return EXIT_GO
+    print(rendered, end="")
+    return EXIT_GO
+
+
+
+def command_init(args: argparse.Namespace) -> int:
+    try:
+        created = init_project(Path(args.directory), args.set_id, args.title, force=args.force)
+    except HarnessError as exc:
+        print(exc, file=sys.stderr)
+        return EXIT_USAGE
+    for path in created:
+        print(path)
+    root = Path(args.directory)
+    print("Next:")
+    print(f"  frontmattering new {root / 'docs' / '10_GUIDE.md'} --profile guide --title \"First guide\"")
+    print(f"  frontmattering validate {root / 'docs'}")
+    print(f"  frontmattering brief {root / 'docs'}")
+    return EXIT_GO
+
+
+def command_new(args: argparse.Namespace) -> int:
+    try:
+        path = new_document(Path(args.path), args.profile, args.title, summary=args.summary, force=args.force)
+    except HarnessError as exc:
+        print(f"Frontmattering authoring error: {exc}", file=sys.stderr)
+        return EXIT_USAGE
+    print(path)
+    print("Next: frontmattering validate " + str(path.parent))
+    return EXIT_GO
+
+
+def command_inventory(args: argparse.Namespace) -> int:
+    try:
+        selection = resolve_corpus(args.paths)
+        payload = build_inventory(selection)
+    except ToolingError as exc:
+        print(exc, file=sys.stderr)
+        return EXIT_USAGE
+    if selected_format(args) == "json":
+        print(json.dumps(payload, indent=2, sort_keys=True))
+    else:
+        print("# Frontmattering corpus inventory")
+        print()
+        print(f"- project_schema: {payload['project']['project_schema']}")
+        print(f"- selected_path_count: {payload['selection']['selected_path_count']}")
+        for key, value in payload["census"].items():
+            print(f"- {key}: {value}")
+        print()
+        print("## Documents")
+        print()
+        for item in payload["documents"]:
+            print(f"- {item['path']}: {item['status']} ({item['reason_code']})")
+        print()
+        print("Claim boundary: deterministic classification only; no semantic profile recommendation is made.")
+    return EXIT_GO
+
+
+def command_promote(args: argparse.Namespace) -> int:
+    if bool(args.output) == bool(args.in_place):
+        print(ToolingError("Promotion output mode is ambiguous", "frontmattering promote", "Exactly one of --output or --in-place is required.", "Choose an explicit destination or intentional in-place write.", error_id="FRONTMATTERING-PROMOTE-OUTPUT-MODE-REQUIRED"), file=sys.stderr)
+        return EXIT_USAGE
+    source = Path(args.input)
+    destination = source if args.in_place else Path(args.output)
+    try:
+        receipt = promote_document(
+            source, profile=args.profile, title=args.title, destination=destination, check_only=args.check
+        )
+    except ToolingError as exc:
+        print(exc, file=sys.stderr)
+        return EXIT_USAGE
+    if args.format == "json":
+        print(json.dumps(receipt, indent=2, sort_keys=True))
+    else:
+        print("# Frontmattering promotion receipt")
+        print()
+        for key in ("terminal_state", "input", "destination", "profile", "title", "title_source", "input_sha256", "output_sha256", "body_bytes_preserved"):
+            print(f"- {key}: {receipt[key]}")
+        print()
+        print("Claim boundary: frontmatter scaffolding and body-byte preservation only; semantic role appropriateness is not verified.")
+    return EXIT_GO
+
+
+def _json_safe(value: Any) -> Any:
+    if isinstance(value, dict):
+        return {str(k): _json_safe(v) for k, v in value.items()}
+    if isinstance(value, (list, tuple)):
+        return [_json_safe(v) for v in value]
+    if isinstance(value, (str, int, float, bool)) or value is None:
+        return value
+    if hasattr(value, "to_dict"):
+        return _json_safe(value.to_dict())
+    return str(value)
+
+
+def _parse_one_document(path: Path, args: argparse.Namespace) -> tuple[dict, int]:
+    if not path.exists() or not path.is_file() or path.suffix.lower() != ".md":
+        raise ToolingError(
+            "Markdown input is required", str(path),
+            "The parse command accepts an existing .md file or a directory with --batch.",
+            "Pass an existing Markdown file, or use --batch with a directory.",
+            {"path": str(path)}, error_id="FRONTMATTERING-PARSE-INPUT-INVALID",
+        )
+    raw = path.read_text(encoding="utf-8", errors="replace")
+    canonical_fm, body, fm_findings = parse_frontmatter(raw)
+    parsed = parse_markdown_text(
+        body,
+        config={"allows_html": args.allows_html, "one_pass": True, "surface_all_links": True},
+        security_profile=args.security_profile,
+        source_path=str(path),
+    )
+    content_security = parsed.metadata.get("security", {})
+    ai_risk = scan_ai_instruction_risk(body, parsed.structure)
+    metadata = dict(parsed.metadata)
+    metadata.pop("security", None)
+    payload = {
+        "schema_version": "frontmattering_document_ir/v0_3",
+        "distribution_version": "0.4.2",
+        "canonical_model_version": "0.1.5",
+        "source": {
+            "path": str(path),
+            "sha256": __import__("hashlib").sha256(raw.encode("utf-8")).hexdigest(),
+            "size_bytes": len(raw.encode("utf-8")),
+        },
+        "frontmatter": {
+            "authority": "canonical_frontmattering_strict_parser",
+            "value": canonical_fm,
+            "findings": [getattr(f, "id", str(f)) for f in fm_findings],
+            "generic_parser_projection": None,
+            "generic_projection_authoritative": False,
+            "body_parser_input": "body_after_strict_frontmattering_frontmatter_boundary",
+        },
+        "markdown": {
+            "implementation": "frontmattering_markdown_parser",
+            "source_lineage": "owned_internal_code",
+            "structure": parsed.structure,
+            "metadata": metadata,
+        },
+        "security": {
+            "content_security": content_security,
+            "ai_instruction_risk": ai_risk,
+        },
+        "claim_boundary": {
+            "establishes": ["token-derived Markdown structure", "content-security findings", "literal AI-instruction-risk advisory findings", "strict Frontmattering frontmatter parse state"],
+            "does_not_establish": ["body semantic correctness", "factual correctness", "semantic prompt-injection detection", "adoption", "release readiness", "production readiness"],
+        },
+    }
+    return payload, (EXIT_GO if not fm_findings else EXIT_FINDING)
+
+
+def command_parse(args: argparse.Namespace) -> int:
+    path = Path(args.path)
+    if args.batch:
+        if not path.is_dir():
+            raise ToolingError("Batch input must be a directory", str(path), "--batch compiles Markdown files under one directory.", "Pass an existing directory.", {"path": str(path)}, error_id="FRONTMATTERING-PARSE-BATCH-INVALID")
+        if not args.output:
+            raise ToolingError("Batch output directory is required", "--output", "Batch mode writes one IR per Markdown file plus a manifest.", "Pass --output DIRECTORY.", {}, error_id="FRONTMATTERING-PARSE-BATCH-OUTPUT-REQUIRED")
+        selection = resolve_corpus([str(path)])
+        out_root = Path(args.output)
+        out_root.mkdir(parents=True, exist_ok=True)
+        records = []
+        terminal = EXIT_GO
+        for src in selection.paths:
+            payload, code = _parse_one_document(src, args)
+            terminal = max(terminal, code)
+            rel = src.relative_to(path.resolve()).with_suffix(src.suffix + ".ir.json")
+            dest = out_root / rel
+            dest.parent.mkdir(parents=True, exist_ok=True)
+            dest.write_text(json.dumps(_json_safe(payload), indent=2, sort_keys=True, ensure_ascii=False)+"\n", encoding="utf-8")
+            records.append({"source": rel.as_posix()[:-8], "ir": rel.as_posix(), "source_sha256": payload["source"]["sha256"]})
+        manifest = {"schema_version":"frontmattering_ir_batch_manifest/v0_3","distribution_version":"0.4.2-pypi-clear","source_root":str(path),"document_count":len(records),"records":records,"selection":selection.payload(),"claim_boundary":"Disposable deterministic projection; source Markdown remains authoritative."}
+        (out_root/"manifest.json").write_text(json.dumps(manifest,indent=2,sort_keys=True)+"\n",encoding="utf-8")
+        print(f"document_ir_batch_written={out_root} documents={len(records)}")
+        return terminal
+    payload, code = _parse_one_document(path, args)
+    output = json.dumps(_json_safe(payload), indent=2, sort_keys=True, ensure_ascii=False) + "\n"
+    if args.output:
+        out = Path(args.output)
+        out.parent.mkdir(parents=True, exist_ok=True)
+        out.write_text(output, encoding="utf-8")
+        print(f"document_ir_written={out}")
+    else:
+        print(output, end="")
+    return code
+
+
+def command_index(args: argparse.Namespace) -> int:
+    index_path = Path(getattr(args, "output", None) or getattr(args, "index", None) or DEFAULT_INDEX)
+    if args.index_action in {"build", "rebuild", "update"}:
+        selection = resolve_corpus([args.corpus])
+        result = build_index(
+            selection.project_root,
+            index_path,
+            source_paths=selection.paths,
+            selection=selection.replay_payload(),
+        )
+        print(json.dumps(result, indent=2, sort_keys=True))
+        return EXIT_GO
+    if args.index_action in {"check", "status"}:
+        proof = ensure_index_fresh(index_path)
+        print(json.dumps({"schema_version":"frontmattering_frontmatter_index_status/v0_1","terminal_state":"CURRENT","freshness_proof":proof.__dict__}, indent=2, sort_keys=True))
+        return EXIT_GO
+    if args.index_action == "delete":
+        if index_path.exists():
+            index_path.unlink()
+        print(json.dumps({"terminal_state":"DELETED","index_path":str(index_path)}, indent=2, sort_keys=True))
+        return EXIT_GO
+    raise ToolingError("Unknown index action", str(args.index_action), "The requested frontmatter-index operation is unsupported.", "Use build, rebuild, update, check, status, or delete.", {}, error_id="FRONTMATTERING-INDEX-ACTION-INVALID")
+
+
+def command_query(args: argparse.Namespace) -> int:
+    result = query_index(Path(args.index or DEFAULT_INDEX), task=args.task, authority=args.authority, role=args.role, target=args.target)
+    print(json.dumps(result, indent=2, sort_keys=True, ensure_ascii=False))
+    return EXIT_GO
+
+
+RUNTIME_WRAPPER_TEMPLATE = r"""#!/usr/bin/env python3
+from __future__ import annotations
+
+import dataclasses
+import hashlib
+import json
+import sys
+import tempfile
+from pathlib import Path
+from typing import Any
+
+MODEL_VERSION = "0.1.5"
+KERNEL_VERSION = "__KERNEL_VERSION__"
+RUNTIME_SCHEMA = "frontmattering_runtime_validate_only/v0_2"
+SPEC_RESOURCE = "resources/FRONTMATTERING_FRONTMATTER_SPEC_v0_1_5.md"
+VALIDATOR_RESOURCE = "validator.py"
+RUNTIME_BUILD_MANIFEST = __RUNTIME_BUILD_MANIFEST__
+
+
+def _package_bytes(relative_path: str) -> bytes:
+    import frontmattering
+    package_dir = Path(frontmattering.__file__).parent
+    resource_path = (package_dir / relative_path).as_posix()
+    loader = getattr(frontmattering, "__loader__", None) or getattr(frontmattering.__spec__, "loader", None)
+    if loader is not None and hasattr(loader, "get_data"):
+        return loader.get_data(resource_path)
+    return Path(resource_path).read_bytes()
+
+
+def _sha256(data: bytes) -> str:
+    return hashlib.sha256(data).hexdigest()
+
+
+def _load_authority():
+    from frontmattering.speccompile import load_spec
+    spec_bytes = _package_bytes(SPEC_RESOURCE)
+    # load_spec is intentionally reused unchanged: the runtime supplies the
+    # bundled spec bytes through a temporary read-only file instead of parsing a
+    # second spec representation.
+    with tempfile.NamedTemporaryFile("wb", suffix="_FRONTMATTERING_FRONTMATTER_SPEC_v0_1_5.md") as handle:
+        handle.write(spec_bytes)
+        handle.flush()
+        return load_spec(Path(handle.name))
+
+
+def _runtime_identity() -> dict[str, Any]:
+    spec_bytes = _package_bytes(SPEC_RESOURCE)
+    validator_bytes = _package_bytes(VALIDATOR_RESOURCE)
+    return {
+        "runtime_schema": RUNTIME_SCHEMA,
+        "runtime_surface": "validate_only",
+        "runtime_packaging": "zipapp_embedded_frontmattering_validator",
+        "canonical_model_version": MODEL_VERSION,
+        "kernel_version": KERNEL_VERSION,
+        "spec_resource": SPEC_RESOURCE,
+        "spec_sha256": _sha256(spec_bytes),
+        "validator_resource": VALIDATOR_RESOURCE,
+        "validator_sha256": _sha256(validator_bytes),
+        **RUNTIME_BUILD_MANIFEST,
+    }
+
+
+def _markdown_paths(targets: list[str]) -> list[Path]:
+    paths: list[Path] = []
+    for raw in targets or ["."]:
+        target = Path(raw)
+        if target.is_file() and target.suffix.lower() == ".md":
+            paths.append(target)
+        elif target.is_dir():
+            paths.extend(p for p in target.rglob("*.md") if p.is_file())
+    return sorted({p.resolve() for p in paths}, key=lambda item: item.as_posix())
+
+
+def _finding_payload(finding: Any) -> dict[str, Any]:
+    if dataclasses.is_dataclass(finding):
+        return dataclasses.asdict(finding)
+    payload = {
+        "id": getattr(finding, "id", str(finding)),
+        "detail": getattr(finding, "detail", ""),
+        "source_path": getattr(finding, "source_path", None),
+        "document_id": getattr(finding, "document_id", None),
+        "field_path": getattr(finding, "field_path", None),
+        "line": getattr(finding, "line", None),
+        "line_text": getattr(finding, "line_text", None),
+        "context": getattr(finding, "context", {}),
+    }
+    return payload
+
+
+def validate(targets: list[str]) -> dict[str, Any]:
+    from frontmattering.validator import validate_docset
+    docs = _markdown_paths(targets)
+    auth = _load_authority()
+    result = validate_docset(docs, auth)
+    findings = [_finding_payload(f) for f in result.get("findings", [])]
+    terminal = "GO" if not findings else "VIOLATED"
+    return {
+        "schema_version": RUNTIME_SCHEMA,
+        "runtime_identity": _runtime_identity(),
+        "terminal_state": terminal,
+        "validation_terminal_state": terminal,
+        "finding_count": len(findings),
+        "findings": findings,
+        "validated_path_count": len(docs),
+        "validated_paths": [str(p) for p in docs],
+        "claim_boundary": {
+            "verifies": [
+                "The packed artifact executed the bundled frontmattering.validate_docset code path.",
+                "The verdict identity binds the bundled Frontmattering frontmatter spec bytes.",
+            ],
+            "does_not_verify": [
+                "Authoring, mutation, indexing, promotion, initialization, or release approval surfaces.",
+                "External adoption, semantic adequacy, or production readiness.",
+            ],
+        },
+    }
+
+
+def _parse_args(argv: list[str]) -> tuple[str, list[str], str]:
+    if len(argv) < 2 or argv[1] != "validate":
+        return "usage", [], "json"
+    paths: list[str] = []
+    fmt = "json"
+    i = 2
+    while i < len(argv):
+        if argv[i] == "--format":
+            if i + 1 >= len(argv) or argv[i + 1] not in {"json"}:
+                return "bad_format", [], fmt
+            fmt = argv[i + 1]
+            i += 2
+        else:
+            paths.append(argv[i])
+            i += 1
+    return "validate", paths, fmt
+
+
+def main(argv: list[str] | None = None) -> int:
+    argv = list(sys.argv if argv is None else argv)
+    action, paths, _fmt = _parse_args(argv)
+    if action == "usage":
+        print("usage: frontmattering-runtime validate <path> [<path> ...] [--format json]", file=sys.stderr)
+        return 2
+    if action == "bad_format":
+        print("frontmattering-runtime only supports --format json", file=sys.stderr)
+        return 2
+    report = validate(paths)
+    print(json.dumps(report, indent=2, sort_keys=True, default=str))
+    return 0 if report["terminal_state"] == "GO" else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv))
+"""
+
+
+def _runtime_payload_files() -> list[Path]:
+    """Return the minimal validate-only runtime payload.
+
+    The runtime must carry the actual validation modules and the spec resource,
+    but it intentionally omits fixtures, authoring tools, generated reports, and
+    mutable/diagnostic surfaces.  Keeping the payload narrow prevents a slow or
+    misleading "whole distribution" runtime while preserving kernel validation
+    semantics.
+    """
+    relative_files = [
+        "__init__.py",
+        "harness_errors.py",
+        "core.py",
+        "speccompile.py",
+        "body_tether.py",
+        "corpus_selection.py",
+        "validator.py",
+        "resources/FRONTMATTERING_FRONTMATTER_SPEC_v0_1_5.md",
+    ]
+    files = [PACKAGE_ROOT / rel for rel in relative_files]
+    missing = [str(path.relative_to(PACKAGE_ROOT)) for path in files if not path.is_file()]
+    if missing:
+        raise ToolingError("Runtime payload assembly failed", "frontmattering runtime pack", f"Required runtime payload files are missing: {missing}", "Restore the validate-only runtime files before packing.")
+    return files
+
+
+def _tree_sha256(files: list[Path]) -> str:
+    h = hashlib.sha256()
+    for path in files:
+        rel = path.relative_to(PACKAGE_ROOT).as_posix().encode("utf-8")
+        data = path.read_bytes()
+        h.update(len(rel).to_bytes(8, "big"))
+        h.update(rel)
+        h.update(len(data).to_bytes(8, "big"))
+        h.update(data)
+    return h.hexdigest()
+
+
+def _runtime_wrapper() -> str:
+    files = _runtime_payload_files()
+    manifest = {
+        "frontmattering_tree_sha256": _tree_sha256(files),
+        "packed_file_count": len(files),
+        "runtime_builder": "frontmattering.__main__.command_runtime_pack",
+    }
+    return RUNTIME_WRAPPER_TEMPLATE.replace(
+        "__KERNEL_VERSION__", "0.4.2"
+    ).replace(
+        "__RUNTIME_BUILD_MANIFEST__", json.dumps(manifest, sort_keys=True)
+    )
+
+
+def _write_runtime_zipapp(out: Path, wrapper: str) -> None:
+    if out.exists() and out.is_dir():
+        shutil.rmtree(out)
+    elif out.exists():
+        out.unlink()
+    out.parent.mkdir(parents=True, exist_ok=True)
+    files = _runtime_payload_files()
+    with zipfile.ZipFile(out, "w", compression=zipfile.ZIP_DEFLATED) as zf:
+        main_info = zipfile.ZipInfo("__main__.py")
+        main_info.date_time = (1980, 1, 1, 0, 0, 0)
+        main_info.external_attr = 0o100755 << 16
+        zf.writestr(main_info, wrapper.encode("utf-8"))
+        for src in files:
+            rel = "frontmattering/" + src.relative_to(PACKAGE_ROOT).as_posix()
+            info = zipfile.ZipInfo(rel)
+            info.date_time = (1980, 1, 1, 0, 0, 0)
+            mode = 0o100755 if os.access(src, os.X_OK) else 0o100644
+            info.external_attr = mode << 16
+            zf.writestr(info, src.read_bytes())
+    try:
+        out.chmod(out.stat().st_mode | 0o111)
+    except OSError as exc:
+        raise ToolingError(
+            "Runtime artifact permission update failed",
+            str(out),
+            "The packed runtime must not silently hide incomplete filesystem finalization.",
+            "Check filesystem permissions or choose a writable output path.",
+            {"error": str(exc)},
+            error_id="FRONTMATTERING-RUNTIME-PACK-CHMOD-FAILED",
+        ) from exc
+
+def command_runtime_pack(args: argparse.Namespace) -> int:
+    out = Path(args.out)
+    wrapper = _runtime_wrapper()
+    _write_runtime_zipapp(out, wrapper)
+    artifact_bytes = out.read_bytes()
+    files = _runtime_payload_files()
+    payload = {
+        "schema_version": "frontmattering_runtime_pack_report/v0_2",
+        "runtime_artifact": str(out),
+        "canonical_model_version": "0.1.5",
+        "kernel_version": "0.4.2",
+        "artifact_format": "python_zipapp",
+        "surface": "validate_only",
+        "artifact_sha256": hashlib.sha256(artifact_bytes).hexdigest(),
+        "spec_sha256": hashlib.sha256(SPEC_PATH.read_bytes()).hexdigest(),
+        "validator_sha256": hashlib.sha256((PACKAGE_ROOT / "validator.py").read_bytes()).hexdigest(),
+        "frontmattering_tree_sha256": _tree_sha256(files),
+        "packed_file_count": len(files),
+        "claim_boundary": {
+            "verifies": [
+                "The runtime artifact carries frontmattering validation modules and the Frontmattering spec resource.",
+                "The runtime surface is validate-only.",
+            ],
+            "does_not_verify": [
+                "Authoring, mutation, release approval, external adoption, or production readiness.",
+            ],
+        },
+    }
+    if args.format == "json":
+        print(json.dumps(payload, indent=2, sort_keys=True))
+    else:
+        print(
+            "runtime_pack=PASS "
+            f"artifact={payload['runtime_artifact']} "
+            f"format={payload['artifact_format']} "
+            f"canonical_model_version={payload['canonical_model_version']} "
+            f"kernel_version={payload['kernel_version']} "
+            f"sha256={payload['artifact_sha256']} "
+            f"spec_sha256={payload['spec_sha256']} "
+            f"validator_sha256={payload['validator_sha256']}"
+        )
+    return EXIT_GO
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = StrictArgumentParser(
+        prog="frontmattering",
+        description="Govern and orient load-bearing Markdown with Frontmattering canonical model v0.1.5 frontmatter.",
+    )
+    parser.add_argument("--version", action="version", version="frontmattering distribution v0.4.2; canonical model v0.1.5")
+    sub = parser.add_subparsers(dest="command", required=True, parser_class=StrictArgumentParser)
+
+    init = sub.add_parser("init", help="Initialize a small Frontmattering document set and package router.")
+    init.add_argument("directory")
+    init.add_argument("--set-id", required=True, help="Stable document-set identifier.")
+    init.add_argument("--title", required=True, help="Human-readable document-set title.")
+    init.add_argument("--force", action="store_true", help="Overwrite generated project files.")
+    init.set_defaults(func=command_init)
+
+    new = sub.add_parser("new", help="Create a canonical document from a practical starter profile.")
+    new.add_argument("path", help="Output Markdown path inside an initialized Frontmattering v0.3 project.")
+    new.add_argument("--profile", choices=sorted(PROFILES), default="guide")
+    new.add_argument("--title", required=True)
+    new.add_argument("--summary")
+    new.add_argument("--force", action="store_true")
+    new.set_defaults(func=command_new)
+
+    inventory = sub.add_parser("inventory", help="Classify selected governed and plain Markdown without writing files.")
+    inventory.add_argument("paths", nargs="*", default=["."])
+    inventory.add_argument("--format", choices=["markdown", "json"], default="markdown")
+    inventory.set_defaults(func=command_inventory)
+
+    promote = sub.add_parser("promote", help="Add a shipped starter-profile frontmatter block to existing plain Markdown.")
+    promote.add_argument("input")
+    promote.add_argument("--profile", choices=sorted(PROFILES), required=True)
+    promote.add_argument("--title")
+    promote.add_argument("--output")
+    promote.add_argument("--in-place", action="store_true")
+    promote.add_argument("--check", action="store_true", help="Emit the proposed receipt without writing.")
+    promote.add_argument("--format", choices=["markdown", "json"], default="markdown")
+    promote.set_defaults(func=command_promote)
+
+
+    parse_cmd = sub.add_parser("parse", help="Emit security-aware JSON document IR using the Frontmattering token-based Markdown parser.")
+    parse_cmd.add_argument("path", help="Markdown file to parse.")
+    parse_cmd.add_argument("--output", help="Write JSON IR to this path, or batch output directory with --batch.")
+    parse_cmd.add_argument("--batch", action="store_true", help="Compile every .md file below PATH into a disposable IR directory.")
+    parse_cmd.add_argument("--security-profile", choices=["permissive", "moderate", "strict"], default="moderate")
+    parse_cmd.add_argument("--allows-html", action="store_true", help="Tokenize raw HTML so it is represented and security-scanned.")
+    parse_cmd.set_defaults(func=command_parse)
+
+    index_cmd = sub.add_parser("index", help="Build and verify the disposable SQLite canonical-frontmatter index.")
+    index_sub = index_cmd.add_subparsers(dest="index_action", required=True, parser_class=StrictArgumentParser)
+    for action in ("build", "rebuild", "update"):
+        sp = index_sub.add_parser(action, help=f"{action.capitalize()} the digest-bound frontmatter index.")
+        sp.add_argument("corpus", nargs="?", default=".")
+        sp.add_argument("--output", default=str(DEFAULT_INDEX))
+        sp.set_defaults(func=command_index)
+    for action in ("check", "status", "delete"):
+        sp = index_sub.add_parser(action, help=f"{action.capitalize()} the frontmatter index.")
+        sp.add_argument("--index", default=str(DEFAULT_INDEX))
+        sp.set_defaults(func=command_index)
+
+    query_cmd = sub.add_parser("query", help="Query only freshness-proven canonical frontmatter projections.")
+    query_cmd.add_argument("--index", default=str(DEFAULT_INDEX))
+    query_cmd.add_argument("--task")
+    query_cmd.add_argument("--authority")
+    query_cmd.add_argument("--role")
+    query_cmd.add_argument("--target", help="Return documents whose relationship target matches this document ID.")
+    query_cmd.set_defaults(func=command_query)
+
+    validate = sub.add_parser("validate", help="Validate one Markdown file, many files, or a directory.")
+    validate.add_argument("paths", nargs="*", default=["."])
+    validate.add_argument("--format", choices=["markdown", "json"], default="markdown")
+    validate.set_defaults(func=command_validate)
+
+    mesh = sub.add_parser("mesh", help="Render the frontmatter-only document mesh.")
+    mesh.add_argument("paths", nargs="*", default=["."])
+    mesh.add_argument("--format", choices=["markdown", "json"], default="markdown")
+    mesh.set_defaults(func=command_mesh)
+
+    brief = sub.add_parser("brief", help="Render the cold-start hazard and reading-order brief.")
+    brief.add_argument("paths", nargs="*", default=["."])
+    brief.add_argument("--task", help="Optional read_when_tags task filter.")
+    brief.add_argument(
+        "--section",
+        choices=["summary", "blocks", "traps", "limits", "do-not", "trust", "reading-order", "defects", "claim-boundary"],
+        default="summary",
+        help="Render the bounded summary or expand one hazard section.",
+    )
+    brief.add_argument("--include-dev", action="store_true",
+                       help="Include fixtures, archive, mesh, usecase, and distro smoke docs.")
+    brief.add_argument("--format", choices=["markdown", "json"], default="markdown")
+    brief.set_defaults(func=command_brief)
+
+    explain = sub.add_parser("explain", help="Explain one FRONTMATTERING-FM finding identifier.")
+    explain.add_argument("finding_id")
+    explain.add_argument("--format", choices=["markdown", "json"], default="markdown")
+    explain.set_defaults(func=command_explain)
+
+    doctor = sub.add_parser("doctor", help="Run the kernel's targeted self-checks.")
+    doctor.add_argument("--format", choices=["markdown", "json"], default="markdown")
+    doctor.set_defaults(func=command_doctor)
+
+    catalog = sub.add_parser(
+        "catalog",
+        help="Print the closed model: root blocks and controlled vocabularies.",
+    )
+    catalog.add_argument("--field", help="Show one field's type, obligation, and allowed values.")
+    catalog.add_argument("--format", choices=["markdown", "json"], default="markdown")
+    catalog.set_defaults(func=command_catalog)
+
+    schema = sub.add_parser(
+        "schema",
+        help="Emit a corpus-aware JSON Schema projection for editor and CI tooling.",
+    )
+    schema.add_argument("paths", nargs="*", help="Optional corpus paths whose router task_catalog widens the task-tag enum.")
+    schema.add_argument("--output", help="Write the schema projection to this path.")
+    schema.add_argument("--check", metavar="PATH", help="Fail if PATH differs from fresh emission.")
+    schema.add_argument("--vscode", action="store_true", help="Print a VS Code YAML schema settings fragment.")
+    schema.set_defaults(func=command_schema)
+
+    tether = sub.add_parser("tether", help="Check or refresh body/frontmatter freshness tethers.")
+    tether_sub = tether.add_subparsers(dest="tether_action", required=True, parser_class=StrictArgumentParser)
+    tether_check = tether_sub.add_parser("check", help="Report FRESH / STALE / UNTETHERED status for governed Markdown.")
+    tether_check.add_argument("paths", nargs="*", default=["."])
+    tether_check.add_argument("--format", choices=["text", "json"], default="text")
+    tether_check.set_defaults(func=command_tether_check)
+    tether_update = tether_sub.add_parser("update", help="Refresh existing body_tether digests; pass --add to create missing tethers.")
+    tether_update.add_argument("paths", nargs="*", default=["."])
+    tether_update.add_argument("--add", action="store_true", help="Add body_tether blocks to documents that do not already carry one.")
+    tether_update.add_argument("--format", choices=["text", "json"], default="text")
+    tether_update.set_defaults(func=command_tether_update)
+
+    runtime = sub.add_parser("runtime", help="Produce or inspect validate-only Frontmattering runtime artifacts.")
+    runtime_sub = runtime.add_subparsers(dest="runtime_action", required=True, parser_class=StrictArgumentParser)
+    runtime_pack = runtime_sub.add_parser("pack", help="Write a self-contained validate-only runtime artifact.")
+    runtime_pack.add_argument("--out", required=True, help="Output path for the runtime artifact.")
+    runtime_pack.add_argument("--format", choices=["text", "json"], default="text")
+    runtime_pack.set_defaults(func=command_runtime_pack)
+
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    try:
+        return args.func(args)
+    except BrokenPipeError:
+        return EXIT_GO
+    except HarnessError as exc:
+        print(exc, file=sys.stderr)
+        return EXIT_INTERNAL
+    except Exception as exc:
+        wrapped = InternalBugError(
+            f"Unexpected kernel exception: {type(exc).__name__}",
+            where="frontmattering.__main__.main",
+            context={"original_error": str(exc), "original_type": type(exc).__name__},
+        )
+        print(wrapped, file=sys.stderr)
+        return EXIT_INTERNAL
+
+
+if __name__ == "__main__":
+    sys.exit(main())