@tanlinfeng/project-docs-workflow 2.2.0 → 2.3.0

package/skills/docs-html-view/references/technical.md

@@ -0,0 +1,151 @@
+# docs-html-view technical reference
+
+## Pinned dependencies
+
+Verified on PyPI 2026-10-14; the set is mutually compatible. Sphinx 9.1.0 requires Python >= 3.12.
+
+| Package | Pin | Note |
+| :--- | :--- | :--- |
+| Sphinx | `Sphinx==9.1.0` | needs Python >= 3.12 |
+| MyST parser | `myst-parser==5.1.0` | Markdown support |
+| RTD theme | `sphinx-rtd-theme==3.1.0` | stock theme via `html_theme` |
+
+`requirements.txt` ships this declaration. `prepare_env.py` installs nothing unless `--install` is passed; the caller runs it only after approval.
+
+## Layout
+
+```
+<project root>/
+  .venv-docs/                     # default render venv (or the project's docs env)
+  docs/                           # Sphinx source root
+    pdr|current|adr/              # approved trees, never modified
+    issues/ agents/ ...           # excluded
+    docsHtmlView/                 # workspace
+      conf.py                     # from assets/conf.py.template
+      guard.py                    # copied from assets/guard.py
+      index.md                    # generated landing page (marked)
+      nav/<tree>/**/index.md      # generated toctrees (marked)
+      docs-html-view.config.json  # optional, user-authored
+      build/html/docsHtmlView/index.html   # landing page (root_doc = docsHtmlView/index)
+```
+
+`docsHtmlView` is the workspace directory name, not the site name.
+
+## Files shipped by this skill
+
+- `scripts/prepare_env.py` — create/reuse a recognized venv; optional pinned install / freeze. Stdlib only.
+- `scripts/gen_nav.py` — generate `index.md` + `nav/**` toctrees (marked files only).
+- `assets/conf.py.template` — the managed `conf.py` for a new site.
+- `assets/guard.py` — the parse/render guard extension.
+- `requirements.txt` — the pins.
+
+## Commands
+
+Inspect is done with normal read-only tools; there is no inspect subcommand and nothing runs the project interpreter before approval. After approval, define the prepared environment's absolute paths from the project root (override `--venv` to reuse a project docs env):
+
+```bash
+SKILL="${SKILL:-$HOME/.agents/skills/docs-html-view}"
+SITE_TITLE="APPROVED TITLE"                           # the confirmed project/site title
+DOCS_PY="$PWD/.venv-docs/bin/python"                 # venv python
+DOCS_SPHINXBUILD="$PWD/.venv-docs/bin/sphinx-build"  # venv sphinx-build
+```
+
+First-time setup (new site only; skip if `docs/docsHtmlView/` already exists and instead show a manual merge plan):
+
+```bash
+python3 "$SKILL"/scripts/prepare_env.py --project-root . --venv .venv-docs
+python3 "$SKILL"/scripts/prepare_env.py --project-root . --venv .venv-docs --install
+mkdir -p docs/docsHtmlView
+( cd docs/docsHtmlView && "$DOCS_PY" -m sphinx.cmd.quickstart -q -p "$SITE_TITLE" -a "AUTHOR" -v "1.0" --no-sep )
+# apply assets/conf.py.template -> docs/docsHtmlView/conf.py
+#   tokens are UNQUOTED; replace __SITE_TITLE__/__AUTHOR__/__RELEASE__ with repr(value)
+# copy assets/guard.py -> docs/docsHtmlView/guard.py
+# remove the generated docs/docsHtmlView/index.rst
+# Makefile: SOURCEDIR = ..   BUILDDIR = build   SPHINXOPTS = -c . -w build/warnings.log
+"$DOCS_PY" "$SKILL"/scripts/gen_nav.py --project-root . --title "$SITE_TITLE"
+mkdir -p docs/docsHtmlView/build
+( cd docs/docsHtmlView && make html SPHINXBUILD="$DOCS_SPHINXBUILD" SPHINXOPTS='-c . -w build/warnings.log' )
+```
+
+Repeat render (same approved scope and title, no re-ask):
+
+```bash
+"$DOCS_PY" "$SKILL"/scripts/gen_nav.py --project-root . --title "$SITE_TITLE"
+mkdir -p docs/docsHtmlView/build
+( cd docs/docsHtmlView && make html SPHINXBUILD="$DOCS_SPHINXBUILD" SPHINXOPTS='-c . -w build/warnings.log' )
+```
+
+No `make`:
+
+```bash
+mkdir -p docs/docsHtmlView/build
+( cd docs/docsHtmlView && "$DOCS_SPHINXBUILD" -b html -c . -d build/doctrees -w build/warnings.log .. build/html )
+```
+
+`gen_nav.py` exits `1` when no approved tree contains documents, so a later `make` cannot silently build a stale site. Warnings (missing/empty trees) go to stderr; `--json` prints the summary on stdout. Without `--title` the site title defaults to `Documentation`; pass the approved `--title` (or set `site_title`) so repeat renders keep the agreed title.
+
+Optional resolved-version snapshot (approved output):
+
+```bash
+python3 "$SKILL"/scripts/prepare_env.py --project-root . --venv .venv-docs \
+    --freeze docs/docsHtmlView/requirements.lock.txt
+```
+
+`prepare_env.py` flags: `--project-root` (default cwd), `--venv` (default `.venv-docs`, relative to project root unless absolute), `--base-python` (interpreter used to create the venv), `--requirements`, `--install`, `--freeze PATH`. It refuses to reuse a path that exists without `pyvenv.cfg`, refuses Python < 3.12, and refuses `--install`/`--freeze` unless the interpreter actually belongs to the target venv. It never installs Python/uv and never uses global/system pip.
+
+`gen_nav.py` flags: `--project-root` (default cwd), `--title` (site title override), `--json`.
+
+
+## Sphinx configuration
+
+`SOURCEDIR=..`, config dir `docs/docsHtmlView` (`-c .`), `BUILDDIR=build` → output `build/html`; `SPHINXOPTS = -c . -w build/warnings.log` (create `build/` first) so warnings are captured for reporting. `root_doc = docsHtmlView/index`, so the landing page is `build/html/docsHtmlView/index.html` (the `build/html/` layout is otherwise unchanged; no redirect or extra page).
+
+`conf.py` uses:
+
+- `include_patterns` — **enumerated**: `docsHtmlView/index.md`, `docsHtmlView/nav/**`, and one `<root>/**` per approved tree. Not a `docsHtmlView/**` wildcard.
+- `exclude_patterns` — build, `.venv-docs`, workspace venvs, VCS internals.
+- `myst_enable_extensions = ["colon_fence", "deflist", "fieldlist"]`, `myst_heading_anchors = 3`.
+- `docs_html_view_allowed_roots` — the same roots, read by `guard.py`.
+
+**Changing `allowed_dirs` is a manual, approved edit with no automatic sync.** Update all three by hand — `include_patterns` and `docs_html_view_allowed_roots` in `conf.py`, and `allowed_dirs` in `docs-html-view.config.json` — then re-run `gen_nav.py`; a mismatch between them must be resolved before `make`. Missing/empty trees are fine (reported and skipped).
+
+### Guard (`assets/guard.py`)
+
+- `builder-inited`: registers a refusing directive for `include`, `literalinclude`, `raw` (case-insensitive; also hit via `eval-rst` and colon fences), and validates each allowed root is a simple relative name resolving inside `docs`.
+- `doctree-read` (priority 100, before Sphinx's asset collectors at 500): rejects any `raw` node that is not purely HTML comment(s)+whitespace (so PDR-template comments pass, active markup fails); for images and `download_reference` nodes, resolves the original reference via `app.env.relfn2path`, requires it inside an approved root using `realpath`/`commonpath` (symlinks rejected), or raises `SphinxError` before any copy; remote targets are replaced with an inline placeholder and a Sphinx warning, never fetched.
+- This is the authoritative boundary and the reason no regex-only scan is used. It guards trusted docs; `conf.py` is trusted executable code and is not sandboxed.
+
+## Optional project config
+
+`docs/docsHtmlView/docs-html-view.config.json` is user-authored and never overwritten. It must be a JSON object; a parse error, a non-object, a non-string `site_title`, a non-string `navigation_order`, or an unsafe `allowed_dirs` entry is refused (not silently dropped).
+
+| Key | Read by | Effect |
+| :--- | :--- | :--- |
+| `site_title` | `gen_nav.py` | site title (also settable via `gen_nav.py --title`) |
+| `allowed_dirs` | `gen_nav.py` | explicit trees; one directory name each (no separators, not hidden, not `build`/`docsHtmlView`); defaults to `pdr`, `current`, `adr` |
+| `navigation_order` | `gen_nav.py` | list of path strings relative to `docs/` placed first, in order; then numeric prefix, then case-insensitive name |
+| `author`, `release` | human / agent only | template token values when applying `conf.py.template`; not read by the scripts |
+| `python` | human / agent only | preferred interpreter when choosing the venv path; not read by the scripts |
+
+## Navigation rules
+
+- Marked generated files only (`% docs-html-view: generated navigation; do not edit`, a MyST comment); unmarked collisions and symlinks are refused.
+- **Preflight before any write:** approved dirs, source trees, and any existing `nav/` (including ancestors) are checked for symlinks; every output path and existing collision is validated before the first write or prune, so a refusal leaves the tree unchanged.
+- `gen_nav.py` exits `1` when no approved tree has documents, and prints warnings (missing/empty trees) to stderr.
+- Hierarchy mirrors the tree; each directory gets a `{toctree}` of its documents and child-index links; entry titles come from the source H1 (path-only toctree entries), so no source text can inject MyST.
+- Directory/site headings are sanitized (no `<`, `>`, backticks, braces, brackets, pipes, newlines).
+- The full ADR tree renders, including retired/deleted tombstones.
+- Re-running prunes only marked stale nav files; user files are never touched.
+
+
+## Approval and consent
+
+The Skill asks once, before any write/install/scaffold, covering packages, environment, files, `.gitignore` additions, output path, and title. There is no stored consent state or fingerprint. Repeated renders inside the approved scope do not re-ask; dependency upgrades, overwriting existing files, or changing the approved roots/range require a fresh ask. Missing trees or malformed required config/venv → report and stop, never guess. The template tokens are unquoted, so substitute each with `repr(value)` (valid, escaped Python literal), never raw interpolation into executable config.
+
+## Limitations
+
+- `.md` / `.rst` only; no `.mdx`.
+- `include` / `literalinclude` / `raw` refused.
+- Remote assets become inline placeholders plus a warning; active HTML is refused (only HTML comments are allowed), and `conf.py` is trusted code.
+- No custom theme, browser, server, or deployment.
+- Failed `make` may leave stale/partial `build/` output; no publisher normalises it.

package/skills/docs-html-view/requirements.txt

@@ -0,0 +1,5 @@
+# docs-html-view — pinned render dependencies (verified on PyPI 2026-10-14)
+# Sphinx 9.1.0 requires Python >= 3.12.
+Sphinx==9.1.0
+myst-parser==5.1.0
+sphinx-rtd-theme==3.1.0

package/skills/docs-html-view/scripts/gen_nav.py

@@ -0,0 +1,306 @@
+#!/usr/bin/env python3
+"""Generate docs-html-view navigation under docs/docsHtmlView.
+
+Writes only marked files inside the workspace: ``docsHtmlView/index.md`` and
+``docsHtmlView/nav/**/index.md``. Never writes into source trees. Validates every
+symlink and collision in a preflight pass *before* the first write or prune, so a
+refusal leaves the tree unchanged. Removes only stale files carrying the marker.
+Runs before ``make html``; it never invokes Sphinx itself.
+
+Exit codes: 0 = generated (or nothing needed); 1 = refused, or no documents in
+the approved trees (so a later ``make`` cannot silently build a stale site).
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import posixpath
+import re
+import sys
+
+MARK = "% docs-html-view: generated navigation; do not edit"
+DEFAULT_ROOTS = ["pdr", "current", "adr"]
+SUFFIXES = (".md", ".rst")
+RESERVED = {"build", "docsHtmlView"}
+BIG = float("inf")
+
+
+def die(msg: str) -> None:
+    sys.exit("refusing: " + msg)
+
+
+def warn(msg: str) -> None:
+    print("warning: " + msg, file=sys.stderr)
+
+
+def sanitize(text: str) -> str:
+    text = re.sub(r"[<>`{}\[\]|]", "", text)
+    return re.sub(r"\s+", " ", text).strip()
+
+
+def display_name(name: str) -> str:
+    name = re.sub(r"^\d+[-_. ]*", "", name).replace("-", " ").replace("_", " ").strip()
+    return sanitize(name) or "section"
+
+
+def num_key(name: str):
+    match = re.match(r"^(\d+)", name)
+    return (0, int(match.group(1))) if match else (1, 0)
+
+
+def has_docs(path: str) -> bool:
+    for _dirpath, _dirnames, filenames in os.walk(path, followlinks=False):
+        if any(f.lower().endswith(SUFFIXES) for f in filenames):
+            return True
+    return False
+
+
+def file_owned(path: str) -> bool:
+    try:
+        with open(path, encoding="utf-8") as fh:
+            return fh.read().lstrip().startswith(MARK)
+    except OSError:
+        die("cannot read " + path)
+
+
+def read_config(workspace: str) -> dict:
+    path = os.path.join(workspace, "docs-html-view.config.json")
+    if not os.path.lexists(path):
+        return {}
+    if os.path.islink(path):
+        die("config is a symlink: " + path)
+    try:
+        with open(path, encoding="utf-8") as fh:
+            data = json.load(fh)
+    except (OSError, ValueError) as exc:
+        die("cannot parse config %s: %s" % (path, exc))
+    if not isinstance(data, dict):
+        die("config must be a JSON object: " + path)
+    return data
+
+
+def validate_dir_name(name: str) -> None:
+    if not name or name in (".", ".."):
+        die("invalid allowed_dirs entry: %r" % (name,))
+    if "/" in name or "\\" in name:
+        die("allowed_dirs entry must be one directory name, no separators: %r" % (name,))
+    if name.startswith("."):
+        die("allowed_dirs entry must not be hidden: %r" % (name,))
+    if name in RESERVED:
+        die("allowed_dirs entry may not be %r" % (name,))
+
+
+def resolve_roots(cfg: dict, docs: str):
+    allowed = cfg.get("allowed_dirs")
+    if allowed is None:
+        candidates = list(DEFAULT_ROOTS)
+    else:
+        if not isinstance(allowed, list):
+            die("allowed_dirs must be a list of simple directory names")
+        for name in allowed:
+            if not isinstance(name, str):
+                die("allowed_dirs entries must be strings")
+            validate_dir_name(name)
+        candidates = list(dict.fromkeys(allowed))
+
+    present, missing = [], []
+    for name in candidates:
+        path = os.path.join(docs, name)
+        if os.path.islink(path):
+            die("approved dir is a symlink: " + path)
+        if os.path.isdir(path) and has_docs(path):
+            present.append(name)
+        else:
+            missing.append(name)
+    return present, missing
+
+
+def assert_no_symlinks(base: str, label: str) -> None:
+    if not os.path.isdir(base):
+        return
+    for dirpath, dirnames, filenames in os.walk(base, followlinks=False):
+        for name in list(dirnames) + filenames:
+            path = os.path.join(dirpath, name)
+            if os.path.islink(path):
+                die("symlink under %s: %s" % (label, path))
+
+
+def toctree(entries, maxdepth=1) -> str:
+    if not entries:
+        return "<!-- (no documents) -->\n"
+    lines = ["```{toctree}", ":maxdepth: %d" % maxdepth, ""] + list(entries) + ["```"]
+    return "\n".join(lines) + "\n"
+
+
+def build_outputs(docs, workspace, roots, order_map, site_title):
+    outputs = {}
+
+    def order_key(base_rel):
+        def key(name):
+            rel = posixpath.join(base_rel, name) if base_rel else name
+            return (order_map.get(rel, BIG), num_key(name), name.casefold())
+        return key
+
+    def generate(source_root, rel_parts, src_dir):
+        base_rel = posixpath.join(source_root, *rel_parts)
+        out_rel = posixpath.join("docsHtmlView", "nav", source_root, *rel_parts)
+        children = []
+        for name in sorted(os.listdir(src_dir)):
+            path = os.path.join(src_dir, name)
+            if os.path.islink(path):
+                die("symlink in source tree: " + path)
+            if os.path.isdir(path):
+                if has_docs(path):
+                    children.append((name, "dir"))
+            elif name.lower().endswith(SUFFIXES):
+                children.append((name, "file"))
+        children.sort(key=lambda item: order_key(base_rel)(item[0]))
+
+        entries = []
+        for name, kind in children:
+            if kind == "dir":
+                entries.append(posixpath.join(name, "index"))
+            else:
+                target = posixpath.join(source_root, *rel_parts, name)
+                entries.append(posixpath.relpath(target, out_rel))
+
+        title = display_name(rel_parts[-1]) if rel_parts else display_name(source_root)
+        out_file = os.path.join(docs, *out_rel.split("/"), "index.md")
+        outputs[out_file] = MARK + "\n\n# " + title + "\n\n" + toctree(entries)
+
+        for name, kind in children:
+            if kind == "dir":
+                generate(source_root, list(rel_parts) + [name], os.path.join(src_dir, name))
+
+    for source_root in roots:
+        generate(source_root, [], os.path.join(docs, source_root))
+
+    index_entries = [posixpath.join("nav", r, "index") for r in roots]
+    outputs[os.path.join(workspace, "index.md")] = (
+        MARK + "\n\n# " + site_title + "\n\n" + toctree(index_entries, maxdepth=2)
+    )
+    return outputs
+
+
+def collision_preflight(outputs, nav_root) -> None:
+    out_abs = {os.path.abspath(p) for p in outputs}
+    for path in sorted(out_abs):
+        if os.path.islink(path):
+            die("symlinked output: " + path)
+        if os.path.lexists(path) and not file_owned(path):
+            die("existing unmarked file: " + path)
+    if os.path.isdir(nav_root):
+        for dirpath, _dirnames, filenames in os.walk(nav_root, followlinks=False):
+            for name in filenames:
+                path = os.path.abspath(os.path.join(dirpath, name))
+                if path in out_abs:
+                    continue
+                if os.path.islink(path):
+                    die("symlinked nav file: " + path)
+                if not file_owned(path):
+                    die("unmarked file under nav/: " + path)
+
+
+def verify_inside(outputs, workspace) -> None:
+    workspace_real = os.path.realpath(workspace)
+    for path in outputs:
+        real = os.path.realpath(path)
+        if real != workspace_real and not real.startswith(workspace_real + os.sep):
+            die("output escapes workspace: " + path)
+
+
+def write_outputs(outputs) -> None:
+    for path in sorted(outputs):
+        os.makedirs(os.path.dirname(path), exist_ok=True)
+        with open(path, "w", encoding="utf-8", newline="\n") as fh:
+            fh.write(outputs[path])
+
+
+def prune(nav_root, outputs) -> None:
+    out_abs = {os.path.abspath(p) for p in outputs}
+    if not os.path.isdir(nav_root):
+        return
+    for dirpath, _dirnames, filenames in os.walk(nav_root, followlinks=False):
+        for name in filenames:
+            path = os.path.abspath(os.path.join(dirpath, name))
+            if path not in out_abs and file_owned(path):
+                os.remove(path)
+    for dirpath, _dirs, _files in os.walk(nav_root, topdown=False):
+        if dirpath == nav_root:
+            continue
+        try:
+            os.rmdir(dirpath)  # only succeeds when empty
+        except OSError:
+            pass
+
+
+def main() -> None:
+    ap = argparse.ArgumentParser(description="Generate docs-html-view navigation (marked files only).")
+    ap.add_argument("--project-root", default=os.getcwd())
+    ap.add_argument("--title", default=None, help="site title override")
+    ap.add_argument("--json", action="store_true", help="print a machine-readable summary on stdout")
+    args = ap.parse_args()
+
+    root = os.path.abspath(args.project_root)
+    docs = os.path.join(root, "docs")
+    if not os.path.isdir(docs):
+        die("no docs/ directory at " + root)
+    if os.path.islink(docs):
+        die("docs/ is a symlink")
+
+    workspace = os.path.join(docs, "docsHtmlView")
+    if not os.path.isdir(workspace):
+        die("no docs/docsHtmlView workspace; run quickstart/setup first")
+    if os.path.islink(workspace):
+        die("docsHtmlView/ is a symlink")
+
+    cfg = read_config(workspace)
+    site_title_cfg = cfg.get("site_title")
+    if site_title_cfg is not None and not isinstance(site_title_cfg, str):
+        die("site_title must be a string")
+    order = cfg.get("navigation_order")
+    if order is None:
+        order = []
+    elif not isinstance(order, list) or not all(isinstance(x, str) for x in order):
+        die("navigation_order must be a list of strings")
+    order_map = {rel.strip("/"): i for i, rel in enumerate(order)}
+
+    roots, missing = resolve_roots(cfg, docs)
+    if missing:
+        warn("missing/empty trees: " + ", ".join(missing))
+    if not roots:
+        print(
+            "no documents in the approved trees; nothing to scaffold (run after adding docs)",
+            file=sys.stderr,
+        )
+        sys.exit(1)
+
+    for name in roots:
+        assert_no_symlinks(os.path.join(docs, name), "source tree " + name)
+    nav_root = os.path.join(workspace, "nav")
+    if os.path.islink(nav_root):
+        die("nav/ is a symlink")
+    assert_no_symlinks(nav_root, "nav/")
+
+    site_title = sanitize(str(site_title_cfg or args.title or "Documentation"))
+    outputs = build_outputs(docs, workspace, roots, order_map, site_title)
+    collision_preflight(outputs, nav_root)
+    verify_inside(outputs, workspace)
+
+    write_outputs(outputs)
+    prune(nav_root, outputs)
+
+    if args.json:
+        print(
+            json.dumps(
+                {"roots": roots, "generated": sorted(os.path.relpath(p, root) for p in outputs)},
+                indent=2,
+            )
+        )
+    else:
+        print("generated %d nav file(s) for roots: %s" % (len(outputs), ", ".join(roots)))
+
+
+if __name__ == "__main__":
+    main()

package/skills/docs-html-view/scripts/prepare_env.py

@@ -0,0 +1,154 @@
+#!/usr/bin/env python3
+"""Prepare the docs render environment for docs-html-view.
+
+Stdlib only. Never installs Python or uv, and never touches global/system
+site-packages. It creates or reuses one *recognized* virtualenv and, only when
+explicitly asked, installs the pinned requirements into that venv.
+
+Run this only AFTER the user has approved the packages, the environment, and the
+files (the Skill asks; this helper stores no consent state).
+"""
+from __future__ import annotations
+
+import argparse
+import os
+import subprocess
+import sys
+
+MIN_PY = (3, 12)
+
+
+def venv_python(venv: str) -> str:
+    if os.name == "nt":
+        return os.path.join(venv, "Scripts", "python.exe")
+    return os.path.join(venv, "bin", "python")
+
+
+def is_recognized_venv(venv: str) -> bool:
+    return os.path.isfile(os.path.join(venv, "pyvenv.cfg"))
+
+
+def python_version(python: str):
+    code = "import sys;print('%d.%d' % sys.version_info[:2])"
+    try:
+        out = subprocess.run(
+            [python, "-I", "-c", code], capture_output=True, text=True, check=True
+        ).stdout.strip()
+    except (OSError, subprocess.CalledProcessError) as exc:
+        return None, str(exc)
+    try:
+        return tuple(int(x) for x in out.split(".")[:2]), out
+    except ValueError:
+        return None, out
+
+
+def run(cmd, cwd=None):
+    print("+ " + " ".join(cmd))
+    return subprocess.run(cmd, cwd=cwd)
+
+
+def has_pip(python: str) -> bool:
+    try:
+        return subprocess.run(
+            [python, "-m", "pip", "--version"], capture_output=True, text=True
+        ).returncode == 0
+    except OSError:
+        return False
+
+
+def venv_prefix(python: str):
+    try:
+        out = subprocess.run(
+            [python, "-c", "import sys;print(sys.prefix)"], capture_output=True, text=True
+        )
+    except OSError:
+        return None
+    return out.stdout.strip() if out.returncode == 0 else None
+
+
+def pip_in_venv(python: str, venv: str):
+    if not has_pip(python):
+        return False, "pip is not available in the interpreter"
+    prefix = venv_prefix(python)
+    if prefix is None or os.path.realpath(prefix) != os.path.realpath(venv):
+        return False, "interpreter does not belong to %s (sys.prefix=%s)" % (venv, prefix)
+    return True, ""
+
+
+def main() -> None:
+    default_req = os.path.join(
+        os.path.dirname(os.path.abspath(__file__)), os.pardir, "requirements.txt"
+    )
+    ap = argparse.ArgumentParser(
+        description="Create/reuse the docs render venv and optionally install pinned requirements."
+    )
+    ap.add_argument("--project-root", default=os.getcwd())
+    ap.add_argument("--venv", default=".venv-docs", help="venv path (relative to project root unless absolute)")
+    ap.add_argument("--base-python", default=None, help="interpreter used to create the venv (default: this one)")
+    ap.add_argument("--requirements", default=default_req)
+    ap.add_argument("--install", action="store_true", help="install the pinned requirements (post-consent)")
+    ap.add_argument("--freeze", metavar="PATH", default=None, help="write `pip freeze` output to PATH (post-consent)")
+    args = ap.parse_args()
+
+    root = os.path.abspath(args.project_root)
+    venv = args.venv if os.path.isabs(args.venv) else os.path.join(root, args.venv)
+    requirements = os.path.abspath(args.requirements)
+
+    if os.path.lexists(venv) and not is_recognized_venv(venv):
+        sys.exit("refusing: %s exists but is not a virtualenv (no pyvenv.cfg); move it aside first" % venv)
+
+    if not is_recognized_venv(venv):
+        base = args.base_python or sys.executable
+        ver, raw = python_version(base)
+        if ver is None or ver < MIN_PY:
+            sys.exit("refusing: %s reports %s; need Python >= %d.%d" % (base, raw, *MIN_PY))
+        print("+ %s -m venv %s" % (base, venv))
+        created = subprocess.run(
+            [base, "-m", "venv", venv], capture_output=True, text=True
+        )
+        if created.returncode != 0:
+            detail = (created.stderr or created.stdout or "").strip()
+            sys.exit(
+                "failed to create virtualenv at %s (exit %d).\n%s\n"
+                "Ensure python3-venv/ensurepip is available, or pass --venv pointing at "
+                "an existing project docs environment." % (venv, created.returncode, detail)
+            )
+    else:
+        print("reusing virtualenv: " + venv)
+
+    py = venv_python(venv)
+    ver, raw = python_version(py)
+    if ver is None or ver < MIN_PY:
+        sys.exit("refusing: venv python reports %s; need Python >= %d.%d" % (raw, *MIN_PY))
+
+    if args.install or args.freeze:
+        ok, why = pip_in_venv(py, venv)
+        if not ok:
+            sys.exit("refusing: %s; point --venv at a working docs environment" % why)
+
+    if args.install:
+        if not os.path.isfile(requirements):
+            sys.exit("requirements not found: " + requirements)
+        result = run(
+            [py, "-m", "pip", "install", "--no-input", "--disable-pip-version-check", "-r", requirements],
+            cwd=root,
+        )
+        if result.returncode != 0:
+            sys.exit("pip install failed (exit %d)" % result.returncode)
+
+    if args.freeze:
+        result = subprocess.run([py, "-m", "pip", "freeze"], capture_output=True, text=True)
+        if result.returncode != 0:
+            sys.exit("pip freeze failed (exit %d)" % result.returncode)
+        dest = args.freeze if os.path.isabs(args.freeze) else os.path.join(root, args.freeze)
+        os.makedirs(os.path.dirname(dest) or ".", exist_ok=True)
+        with open(dest, "w", encoding="utf-8", newline="\n") as fh:
+            fh.write(result.stdout)
+        print("wrote freeze: " + dest)
+
+    print("python: " + py)
+    print("install: " + ("yes" if args.install else "no"))
+
+
+if __name__ == "__main__":
+    main()