@tanlinfeng/project-docs-workflow 2.2.0 → 3.0.0

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@tanlinfeng/project-docs-workflow",
-  "version": "2.2.0",
+  "version": "3.0.0",
   "publishConfig": {
     "access": "public"
   },
-  "description": "项目文档工作流 skill 包：提供 issue tracker / ADR / PDR / 术语表与工作流约定，自带轻量依赖 skill 与 ref 兜底，可独立分发。",
+  "description": "项目文档工作流 skill 包：提供 issue tracker / ADR / PDR / 术语表与工作流约定；随包分发主 skill 与 doc-opt / docs-html-view，内置依赖回退 ref（不随包分发独立依赖 skill），可独立使用。",
   "license": "MIT",
   "bin": {
     "project-docs-workflow": "bin/install.js"

package/skills/docs-html-view/SKILL.md

@@ -0,0 +1,119 @@
+---
+name: docs-html-view
+description: Render a project's PDR / Current / ADR docs to local HTML with Sphinx + MyST (stock RTD theme), after a read-only inspection and explicit approval.
+disable-model-invocation: true
+argument-hint: "[project root]"
+---
+
+# Docs HTML View
+
+Render the human-readable documentation trees of a project (`docs/pdr`, `docs/current`, `docs/adr`) into a local HTML site using **standard Sphinx** with MyST (`myst_parser`) and the **stock** `sphinx_rtd_theme`. There is no custom renderer: scaffolding uses `sphinx-quickstart`, navigation is a small generated-toctree helper, and the build is `make html` (or a plain `sphinx-build`). The output is a local folder you open yourself; nothing is served or deployed.
+
+This skill is manually triggered and never automatic, and it never fetches anything at build time. It may install the pinned render dependencies, but only after your explicit approval. Inspect read-only, ask for approval **once**, then first-time setup and repeat manual renders run without re-asking — until a setting changes.
+
+## Boundaries
+
+- **User-triggered only.** Never install, scaffold, or build while editing docs.
+- **Bounded writes.** The approved set is: `docs/docsHtmlView/` (config, generated navigation, build output), the approved render environment directory (e.g. `.venv-docs/`), and any `.gitignore` additions you approved. Rendering reads `docs/pdr`, `docs/current`, `docs/adr` and never rewrites them, and it never writes into source trees.
+- **Approved trees only.** Default trees are `pdr`, `current`, `adr`; a tree may be extended explicitly in the config file, never auto-expanded. `docs/issues`, `docs/agents`, tooling, and build output are excluded. A missing or empty tree is reported, not created. No documents in the approved trees → **stop: do not create `docs/docsHtmlView/`, do not scaffold, do not build.**
+- **Stock theme.** No custom UI/design work.
+- **No invented links.** Navigation is generated from the real tree; no cross-tree associations are added and no document bodies are rewritten.
+- **No browser/server/deploy.** Producing HTML is the end. README/local output only.
+
+## Flow
+
+Run from the project root (`cwd`). Define the skill directory and, after approval, the prepared environment's absolute paths once — `DOCS_PY` is the venv **python**, `DOCS_SPHINXBUILD` the venv **sphinx-build**:
+
+```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"                 # or the project's existing docs env
+DOCS_SPHINXBUILD="$PWD/.venv-docs/bin/sphinx-build"  # same env
+```
+
+1. **Inspect (read-only).** Use normal read-only tools (`ls`, `read`, `grep`) to learn the project: which of `docs/pdr`, `docs/current`, `docs/adr` exist and contain documents, whether `docs/docsHtmlView/` already exists, which Python/venv exists, and the real project/site title. **Never execute the project's interpreter or `conf.py` before approval.** If no approved tree contains documents, stop here — there is nothing to render. Report the plan: pins, environment path, files created, `.gitignore` additions, output path, and title.
+
+2. **Ask once.** Get explicit approval **before any write, install, or scaffold**. Cover concretely: packages/pins (`requirements.txt`), where the environment lives, the pip command, the files created, the `.gitignore` additions you propose (e.g. `.venv-docs/`, `docs/docsHtmlView/build/`), the build/output paths (`docs/docsHtmlView/build/html`), and the confirmed site title — `docsHtmlView` is a directory name, not the site name.
+   - Within the approved scope, repeated manual rendering does **not** re-ask.
+   - Dependency upgrades, overwriting existing files, or changing the approved root/range **do** require a fresh ask.
+
+3. **Prepare the environment (approved only).** Prefer an existing project docs environment; otherwise a project-root `.venv-docs`. No global/system installs, no automatic `uv`/Python installation. If no suitable Python exists, stop and tell the user. The helper is stdlib-only, so run it with any working Python; then point `DOCS_PY`/`DOCS_SPHINXBUILD` at the environment it prepared:
+
+   ```bash
+   python3 "$SKILL"/scripts/prepare_env.py --project-root . --venv .venv-docs
+   python3 "$SKILL"/scripts/prepare_env.py --project-root . --venv .venv-docs --install
+   ```
+
+   The helper only creates/reuses a recognized venv (a directory with `pyvenv.cfg`; it refuses to clobber a non-venv) and installs the pinned requirements only when `--install` is passed (after your approval). It never runs on ordinary doc edits, and distributing the skill package installs nothing.
+
+4. **First-time setup (approved, only when `docs/docsHtmlView/` does not exist).** The approved trees already exist, so only the workspace dir is created — **after** the inspection confirmed documents exist and you approved:
+
+   ```bash
+   mkdir -p docs/docsHtmlView
+   ( cd docs/docsHtmlView && "$DOCS_PY" -m sphinx.cmd.quickstart -q -p "$SITE_TITLE" -a "AUTHOR" -v "1.0" --no-sep )
+   ```
+
+   Then, **only for the newly generated config**:
+    - replace the generated `conf.py` using `assets/conf.py.template`; the template leaves `__SITE_TITLE__` / `__AUTHOR__` / `__RELEASE__` **unquoted**, so use `template_text.replace(token, repr(value))` for each token. Never interpolate raw user text unescaped into executable config source;
+   - copy `assets/guard.py` to `docs/docsHtmlView/guard.py`;
+   - remove the quickstart's generated `index.rst` (the landing page is generated `index.md`);
+   - edit the generated `Makefile`: set `SOURCEDIR = ..` and `BUILDDIR = build` (replace the generated `SOURCEDIR = .` / `BUILDDIR = _build`), and either change the generated `SPHINXOPTS    ?=` line to `SPHINXOPTS = -c . -w build/warnings.log` or pass it on the `make` command line (below). Optionally remove the now-unused generated `_build/`. (`make.bat` may be edited the same way; not required on Linux/macOS.)
+
+   If `docs/docsHtmlView/` already exists, **do not overwrite**: present an explicit manual merge plan and let the user apply it. Re-running setup never re-scaffolds.
+
+5. **Generate navigation (before every build).** The helper writes only marked files under the workspace, exits non-zero if no approved tree has documents, and never runs Sphinx:
+
+   ```bash
+   "$DOCS_PY" "$SKILL"/scripts/gen_nav.py --project-root . --title "$SITE_TITLE"
+   ```
+
+   Always pass the approved title (or set `site_title` in the config); without it, the site title silently defaults to `Documentation`. Repeat renders reuse the same agreed `SITE_TITLE`, without re-asking or switching titles.
+
+6. **Build (repeatable without re-approval).**
+
+   ```bash
+   mkdir -p docs/docsHtmlView/build
+   ( cd docs/docsHtmlView && make html SPHINXBUILD="$DOCS_SPHINXBUILD" SPHINXOPTS='-c . -w build/warnings.log' )
+   ```
+
+   If `make` is unavailable, use the same paths explicitly:
+
+   ```bash
+   mkdir -p docs/docsHtmlView/build
+   ( cd docs/docsHtmlView && "$DOCS_SPHINXBUILD" -b html -c . -d build/doctrees -w build/warnings.log .. build/html )
+   ```
+
+   Output lands under `docs/docsHtmlView/build/html`; because `root_doc = docsHtmlView/index`, the **landing page is `docs/docsHtmlView/build/html/docsHtmlView/index.html`** (open that file). The `build/html/` directory layout itself is unchanged — no redirect or extra index page is generated. Warnings go to `docs/docsHtmlView/build/warnings.log`. The `build/` dir is created only after approval. Source-doc edits are legitimate rebuilds. A change to an approved setting (roots, title, environment) requires a fresh ask. Do not wrap `make`/`sphinx-build` in another script.
+
+   **Changing the approved trees is a manual, approved edit.** If `allowed_dirs` changes, update all three together by hand: `include_patterns` and `docs_html_view_allowed_roots` in `docs/docsHtmlView/conf.py`, and `allowed_dirs` in `docs/docsHtmlView/docs-html-view.config.json`; then re-run `gen_nav`. There is no automatic sync, and a mismatch must be resolved before `make`. A missing/empty tree is fine (reported, skipped).
+
+7. **Report.** Summarise the normal Sphinx result — see Statuses below.
+
+## Safety model
+
+The boundary is a small template Sphinx extension (`assets/guard.py`), not a build orchestrator. It is a best-effort guard for **trusted** project docs, not a universal sandbox; the project's own `conf.py` remains executable Python.
+
+- **File insertion blocked at parse time:** `include`, `literalinclude`, and `raw` directives are replaced by a refusing directive (case-insensitive, so `INCLUDE` too; also reached through `eval-rst` and MyST colon fences). Active/raw HTML is refused; only pure HTML-comment (plus whitespace) raw nodes are allowed, so the harmless `<!-- ... -->` comments in the PDR templates render — but no comment+markup smuggling. No regex-only scan is relied on.
+- **Local assets checked before copy:** at `doctree-read` (priority 100, before Sphinx's asset collectors copy anything) every parsed image and download target is resolved with the environment's reference resolver and must resolve (symlinks included) inside an approved root, or the build fails. Reference-style images, `:download:`, and uppercase directives are covered.
+- **Remote assets are never fetched:** remote images/downloads are replaced with an inline placeholder and a Sphinx warning is emitted, so a clean build is not reported as full fidelity.
+- **Navigation is generated, not authored:** `gen_nav.py` writes only marked files (`% docs-html-view: generated navigation; do not edit`, a MyST comment that renders as no content), sanitizes generated titles (no `<`, `>`, backticks, braces, brackets, pipes, or newlines), and runs a full preflight — approved dirs, source trees, and any existing `nav/` (including ancestors) are checked for symlinks, and every output/collision is validated before the first write, so a refusal leaves the tree unchanged. It removes only its own marked stale nav files and never writes into source trees.
+
+Approved scope that links out to excluded docs produces ordinary Sphinx "missing reference" warnings; those are reported, never auto-added.
+
+## Statuses
+
+Read the normal Sphinx exit code and the warning log (`build/warnings.log`):
+
+- **clean success** — build exited 0 and the warning log is empty.
+- **preview with warnings** — build exited 0 but the warning log has entries; report the first warnings and the log path.
+- **failure** — `gen_nav.py` refused (or exited 1 with no documents), `guard.py` rejected the build, or Sphinx exited non-zero. A failed `make` may leave stale or partial output under `build/`; state that clearly and do not present it as a fresh build. There is no publisher step: whatever `make` left is what exists.
+
+## Limitations
+
+- Supported sources are `.md` and `.rst` under the approved trees; `.mdx` and other extensions are not rendered.
+- `include` / `literalinclude` / `raw` are refused; this is not an arbitrary-Markdown renderer.
+- Remote images/downloads become inline placeholders plus a Sphinx warning; active HTML is refused, so "no browser network" is not claimed for arbitrary markup.
+- The guard is a trusted-doc guardrail, not a sandbox for untrusted input.
+- The dependency helper installs only the pinned requirements, only with `--install`, and only after consent; it never installs Python or uv.
+
+See `references/technical.md` for the exact commands, template apply steps, config keys, and navigation rules.

package/skills/docs-html-view/agents/openai.yaml

@@ -0,0 +1,5 @@
+interface:
+  display_name: "Docs HTML View"
+  short_description: "Render PDR/Current/ADR docs to local HTML after approval"
+policy:
+  allow_implicit_invocation: false

package/skills/docs-html-view/assets/conf.py.template

@@ -0,0 +1,44 @@
+# docs-html-view managed Sphinx config (template).
+#
+# Apply only to the conf.py that sphinx-quickstart just generated for a NEW site:
+# copy this file over docs/docsHtmlView/conf.py and replace the __TOKENS__ below,
+# then copy assets/guard.py to docs/docsHtmlView/guard.py. For an existing site,
+# do not overwrite: show the user a manual merge plan first.
+import os
+import sys
+
+sys.path.insert(0, os.path.abspath(os.path.dirname(__file__)))
+
+project = __SITE_TITLE__
+author = __AUTHOR__
+release = __RELEASE__
+
+extensions = ["myst_parser", "guard"]
+html_theme = "sphinx_rtd_theme"
+html_theme_options = {}
+
+source_suffix = {".md": "markdown", ".rst": "restructuredtext"}
+root_doc = "docsHtmlView/index"
+
+# Enumerate exactly: landing page, generated navigation, and the approved trees.
+# Deliberately NOT a docsHtmlView/** wildcard, so foreign workspace files are ignored.
+include_patterns = [
+    "docsHtmlView/index.md",
+    "docsHtmlView/nav/**",
+    "pdr/**",
+    "current/**",
+    "adr/**",
+]
+
+exclude_patterns = [
+    "docsHtmlView/build/**",
+    "docsHtmlView/.venv*/**",
+    ".venv-docs/**",
+    "**/.git/**",
+]
+
+myst_enable_extensions = ["colon_fence", "deflist", "fieldlist"]
+myst_heading_anchors = 3
+
+# Read by guard.py; must list the same roots as include_patterns above.
+docs_html_view_allowed_roots = ["pdr", "current", "adr"]

package/skills/docs-html-view/assets/guard.py

@@ -0,0 +1,128 @@
+"""docs-html-view guard: a best-effort parse/render guard for trusted project docs.
+
+This is a trusted-document renderer, not a universal sandbox. It blocks
+file-insertion directives, refuses active/raw HTML (allowing only HTML comments),
+and checks local image/download references against the approved roots at
+``doctree-read`` (before Sphinx's asset collectors copy anything). Remote
+images/downloads are never fetched. The project's own ``conf.py`` remains
+executable Python.
+"""
+from __future__ import annotations
+
+import os
+import re
+from urllib.parse import urlparse
+
+from docutils import nodes
+from docutils.parsers.rst import Directive, directives
+from sphinx import addnodes
+from sphinx.errors import SphinxError
+from sphinx.util import logging
+
+logger = logging.getLogger(__name__)
+
+BLOCKED = ("include", "literalinclude", "raw")
+# A raw node is allowed only when it is entirely HTML comment(s) and whitespace.
+# This permits the harmless `<!-- ... -->` comments used in the PDR templates while
+# still refusing any active markup (no comment+script smuggling).
+_COMMENT_ONLY = re.compile(r"\s*(?:<!--.*?-->\s*)*", re.DOTALL)
+
+
+class _Blocked(Directive):
+    has_content = True
+    optional_arguments = 1
+    final_argument_whitespace = True
+
+    def run(self):
+        raise SphinxError("docs-html-view: '%s' directive is not allowed" % self.name)
+
+
+def _block_directives(app):
+    # Registered after extensions load; docutils lowercases names, so this also
+    # catches INCLUDE and directives reached through eval-rst or colon fences.
+    for name in BLOCKED:
+        directives.register_directive(name, _Blocked)
+
+
+def _validate_roots(app):
+    """Every allowed root must be a simple relative name that resolves inside docs."""
+    srcdir_real = os.path.realpath(app.srcdir)
+    for name in app.config.docs_html_view_allowed_roots:
+        if not isinstance(name, str) or not name or os.path.isabs(name) or "\\" in name:
+            raise SphinxError("docs-html-view: invalid allowed root %r" % (name,))
+        parts = name.split("/")
+        if any(part in ("", ".", "..") for part in parts):
+            raise SphinxError("docs-html-view: allowed root must be a simple relative name: %r" % (name,))
+        root_real = os.path.realpath(os.path.join(app.srcdir, name))
+        try:
+            inside = os.path.commonpath([root_real, srcdir_real]) == srcdir_real
+        except ValueError:
+            inside = False
+        if not inside:
+            raise SphinxError("docs-html-view: allowed root escapes docs: %r" % (name,))
+
+
+def _remote(uri: str) -> bool:
+    return bool(urlparse(uri).scheme) or uri.startswith("//")
+
+
+def _within(path: str, roots) -> bool:
+    real = os.path.realpath(path)
+    for root in roots:
+        root_real = os.path.realpath(root)
+        try:
+            if os.path.commonpath([real, root_real]) == root_real:
+                return True
+        except ValueError:
+            continue
+    return False
+
+
+def _guard_assets(app, doctree):
+    docname = app.env.docname
+    roots = [os.path.join(app.srcdir, r) for r in app.config.docs_html_view_allowed_roots]
+
+    for node in doctree.findall(nodes.raw):
+        if not _COMMENT_ONLY.fullmatch(node.astext() or ""):
+            raise SphinxError("docs-html-view: active/raw HTML is not allowed in %s" % docname)
+
+    def check(uri, kind):
+        """True if usable locally, False if remote; raises when local-but-outside."""
+        if not uri:
+            return True
+        if _remote(uri):
+            return False
+        clean = uri.split("#", 1)[0]
+        try:
+            _rel, abspath = app.env.relfn2path(clean, docname)
+        except Exception:
+            abspath = None
+        if abspath is None or not _within(abspath, roots):
+            raise SphinxError(
+                "docs-html-view: %s outside approved roots in %s: %s" % (kind, docname, uri)
+            )
+        return True
+
+    for node in doctree.findall(nodes.image):
+        uri = node.get("uri", "")
+        if check(uri, "image"):
+            continue
+        logger.warning("docs-html-view: remote image not fetched: %s", uri, location=docname)
+        node.replace_self(nodes.emphasis("", "[remote image not fetched] " + uri))
+
+    for node in doctree.findall(addnodes.download_reference):
+        uri = node.get("reftarget") or node.get("refuri") or ""
+        if check(uri, "download"):
+            continue
+        logger.warning("docs-html-view: remote download not fetched: %s", uri, location=docname)
+        node.replace_self(nodes.emphasis("", "[remote download not fetched] " + uri))
+
+
+def setup(app):
+    app.add_config_value("docs_html_view_allowed_roots", [], "env")
+    app.connect("builder-inited", _block_directives)
+    app.connect("builder-inited", _validate_roots)
+    # doctree-read (priority 100) so we run before Sphinx's asset collectors (500),
+    # which copy downloads during read and register images for copy.
+    app.connect("doctree-read", _guard_assets, priority=100)
+    return {"parallel_read_safe": True, "parallel_write_safe": True}

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