@mseep/open-computer-use 1.0.0

package/scripts/check-config.sh

@@ -0,0 +1,141 @@
+#!/usr/bin/env bash
+# SPDX-License-Identifier: FSL-1.1-Apache-2.0
+# Copyright (c) 2025 Open Computer Use Contributors
+#
+# Pre-flight check for .env before `docker compose up`. Catches the common
+# silent-fail misconfigurations (PUBLIC_BASE_URL default, half-enabled feature
+# groups, weak passwords) at invocation time rather than in production.
+#
+# Usage:   ./scripts/check-config.sh [path/to/.env]
+# Exit 0 on clean config or only WARNs; exit 1 if any ERR is reported.
+
+set -uo pipefail
+
+ENV_FILE="${1:-.env}"
+
+if [[ ! -f "$ENV_FILE" ]]; then
+    echo "ERROR: env file not found: $ENV_FILE" >&2
+    echo "  Hint: cp .env.example .env && edit it" >&2
+    exit 1
+fi
+
+# Load .env into the current shell. `set -a` auto-exports; `|| true` around
+# source protects against malformed lines triggering `set -u` aborts. We DO
+# want `set -u` off temporarily because .env.example keeps many vars unset.
+set +u
+set -a
+# shellcheck disable=SC1090
+source "$ENV_FILE"
+set +a
+
+errors=0
+warns=0
+oks=0
+
+section() {
+    printf '\n== %s ==\n' "$1"
+}
+
+ok()   { printf '  [OK]   %s\n' "$1"; oks=$((oks + 1)); }
+warn() { printf '  [WARN] %s\n' "$1"; warns=$((warns + 1)); }
+err()  { printf '  [ERR]  %s\n' "$1"; errors=$((errors + 1)); }
+
+echo "Config check for open-computer-use"
+echo "=================================="
+echo "Env file: $ENV_FILE"
+
+# ----- REQUIRED -----
+section "REQUIRED"
+
+pbu="${PUBLIC_BASE_URL:-}"
+# Strip a single trailing slash so `http://computer-use-server:8081/` still
+# matches the internal default check below.
+pbu="${pbu%/}"
+if [[ -z "$pbu" ]]; then
+    err "PUBLIC_BASE_URL is unset (browser-reachable URL of the Computer Use server)"
+elif [[ "$pbu" == "http://computer-use-server:8081" ]]; then
+    err "PUBLIC_BASE_URL is still the internal-DNS default — browser can't reach it"
+else
+    ok "PUBLIC_BASE_URL = $pbu"
+fi
+
+ap="${ADMIN_PASSWORD:-}"
+case "$ap" in
+    ""|admin|change-me)
+        warn "ADMIN_PASSWORD is weak/default ('$ap') — fine for local dev only" ;;
+    *)
+        ok "ADMIN_PASSWORD is set" ;;
+esac
+
+wsk="${WEBUI_SECRET_KEY:-}"
+case "$wsk" in
+    ""|change-me)
+        warn "WEBUI_SECRET_KEY is unset or placeholder — sessions won't survive restart" ;;
+    *)
+        ok "WEBUI_SECRET_KEY is set" ;;
+esac
+
+pg="${POSTGRES_PASSWORD:-openwebui}"
+if [[ "$pg" == "openwebui" ]]; then
+    warn "POSTGRES_PASSWORD is still the default ('openwebui') — change for production"
+else
+    ok "POSTGRES_PASSWORD is set"
+fi
+
+if [[ -z "${MCP_API_KEY:-}" ]]; then
+    warn "MCP_API_KEY is empty — /mcp endpoints have no auth (fine for local dev)"
+else
+    ok "MCP_API_KEY is set"
+fi
+
+oak="${OPENAI_API_KEY:-}"
+if [[ -z "$oak" || "$oak" == "sk-..." ]]; then
+    warn "OPENAI_API_KEY is empty/placeholder — the chat completion will not work"
+else
+    ok "OPENAI_API_KEY is set"
+fi
+
+# ----- OPTIONAL FEATURE GROUPS (all-or-nothing) -----
+section "OPTIONAL FEATURE GROUPS"
+
+# Vision: VISION_API_KEY + VISION_API_URL + VISION_MODEL
+vak="${VISION_API_KEY:-}"
+vau="${VISION_API_URL:-}"
+vmo="${VISION_MODEL:-}"
+vision_set=0
+for v in "$vak" "$vau" "$vmo"; do
+    if [[ -n "$v" ]]; then vision_set=$((vision_set + 1)); fi
+done
+case "$vision_set" in
+    0) ok "Vision: not configured (skipping group)" ;;
+    3) ok "Vision: all three set" ;;
+    *) err "Vision: partial config (only $vision_set/3 set) — set all three or none" ;;
+esac
+
+# MCP Tokens Wrapper: MCP_TOKENS_URL + MCP_TOKENS_API_KEY
+mtu="${MCP_TOKENS_URL:-}"
+mtk="${MCP_TOKENS_API_KEY:-}"
+if [[ -z "$mtu" && -z "$mtk" ]]; then
+    ok "MCP Tokens: not configured (skipping group)"
+elif [[ -n "$mtu" && -n "$mtk" ]]; then
+    ok "MCP Tokens: both configured"
+else
+    err "MCP Tokens: partial config — set BOTH MCP_TOKENS_URL and MCP_TOKENS_API_KEY or neither"
+fi
+
+# Anthropic sub-agent presence (single toggle, no pairing required)
+if [[ -n "${ANTHROPIC_AUTH_TOKEN:-}" ]]; then
+    ok "Claude Code sub-agent: enabled"
+fi
+
+# ----- SUMMARY -----
+section "SUMMARY"
+printf 'OK: %d  WARN: %d  ERR: %d\n' "$oks" "$warns" "$errors"
+
+if [[ "$errors" -gt 0 ]]; then
+    echo
+    echo "Fix the [ERR] items above before running 'docker compose up'."
+    exit 1
+fi
+
+exit 0

package/scripts/docs-lint/ai-slop-detector.sh

@@ -0,0 +1,202 @@
+#!/usr/bin/env bash
+# SPDX-License-Identifier: FSL-1.1-Apache-2.0
+# Copyright (c) 2025 Open Computer Use Contributors
+#
+# AI-slop detector — patterns that flag AI-generated bloat.
+#
+# Complements vale (which checks banned vocab/phrases in prose). This script
+# catches structural patterns vale can't see: TOCs in short docs, reflexive
+# Conclusion sections, decorative dividers for one-paragraph content,
+# stub headings, file openings that restate project scope.
+#
+# Exits 1 on any hit.
+
+set -euo pipefail
+
+ROOT="$(git rev-parse --show-toplevel)"
+cd "$ROOT"
+
+fail=0
+
+# Scope: docs/architecture/, CLAUDE.md, README.md, CONTRIBUTING.md.
+mapfile -d '' files < <(
+  find docs/architecture -name '*.md' -print0 2>/dev/null
+  printf '%s\0' CLAUDE.md README.md CONTRIBUTING.md 2>/dev/null
+)
+
+check() {
+  local file="$1" lines="$2"
+
+  # 1. File begins with "open-computer-use is …" (restating project scope).
+  if awk 'NR<=20 && /^[Oo]pen [Cc]omputer [Uu]se is /' "$file" | grep -q .; then
+    echo "FAIL: $file restates project scope in first 20 lines"
+    fail=1
+  fi
+
+  # 2. Conclusion / Summary section in a short doc (< 1000 lines).
+  if (( lines < 1000 )) && grep -qE '^##+ (Conclusion|Summary|In conclusion|TL;DR)$' "$file"; then
+    echo "FAIL: $file has a Conclusion/Summary section in a doc shorter than 1000 lines"
+    fail=1
+  fi
+
+  # 3. Table of Contents in a short doc (≤ 500 lines).
+  if (( lines <= 500 )) && grep -qE '^##+ (Table of [Cc]ontents|TOC|Contents)$' "$file"; then
+    echo "FAIL: $file has a TOC in a doc ≤ 500 lines (headings already navigate)"
+    fail=1
+  fi
+
+  # 4. Decorative emoji headers.
+  if grep -qE '^##+ [^A-Za-z0-9`<\(\[]' "$file"; then
+    if grep -nE '^##+ [^A-Za-z0-9`<\(\[]' "$file" | grep -v '^[0-9]*:##* [#]' > /dev/null; then
+      echo "WARN: $file may have decorative-character headings (manually verify)"
+    fi
+  fi
+
+  # 5. Stub headings (heading immediately followed by another heading or EOF).
+  awk '
+    /^##+ / {
+      cur=$0; line=NR
+      while ((getline next_line) > 0) {
+        if (next_line ~ /^[ \t]*$/) continue
+        if (next_line ~ /^##+ /) {
+          print FILENAME ":" line ": stub heading (no content before next heading): " cur
+          exit 1
+        }
+        break
+      }
+    }
+  ' "$file" | grep . && fail=1 || true
+
+  # 6. Self-referential CI / doc-rules meta-noise. Reader does not need to be
+  #    told about our line caps, vale lint, banned-vocab list, "diagrams budget"
+  #    inside the doc itself. CLAUDE.md is the rule source; the doc carries
+  #    content, not rules about itself.
+  if grep -nEi '(kept within the [^.]*budget|≤[0-9]+-line (form|cap|budget)|CLAUDE\.md (rules|conventions|line cap|inline-mermaid|Diagrams (budget|rules|inline))|preserve[sd]? .{0,40}(banned-vocab|vale lint)|the surrounding backticks preserve|against (our|the) (project )?banned-vocab)' "$file" > /dev/null; then
+    grep -nEi '(kept within the [^.]*budget|≤[0-9]+-line (form|cap|budget)|CLAUDE\.md (rules|conventions|line cap|inline-mermaid|Diagrams (budget|rules|inline))|preserve[sd]? .{0,40}(banned-vocab|vale lint)|the surrounding backticks preserve|against (our|the) (project )?banned-vocab)' "$file"
+    echo "FAIL: $file contains self-referential CI / doc-rules meta-noise"
+    fail=1
+  fi
+
+  # 7. "Holds in spirit" / "honest about" / "as a binding artifact for" —
+  #    hedge phrasing that adds no factual content.
+  if grep -nEi '(hold[s]? in spirit|honest about (not )?being|the binding artifact for|is what the contract binds)' "$file" > /dev/null; then
+    grep -nEi '(hold[s]? in spirit|honest about (not )?being|the binding artifact for|is what the contract binds)' "$file"
+    echo "FAIL: $file contains hedge / pompous phrasing"
+    fail=1
+  fi
+
+  # 8. "the only X" / "is the only" boastful framing — superlative without a
+  #    measurable referent. CLAUDE.md "no adjectives without measurable
+  #    referent".
+  #    Allowed: "is the only zone" / "is the only path" in legitimate context.
+  #    Banned: "is the only plaintext segments and …" boastful style.
+  if grep -nEi '\b(is|are) the only [a-z]+ (and|listed|that)\b' "$file" > /dev/null; then
+    grep -nEi '\b(is|are) the only [a-z]+ (and|listed|that)\b' "$file"
+    echo "FAIL: $file contains boastful 'the only X' framing"
+    fail=1
+  fi
+
+  # 9. Triple parallel construction "X stay in Y; X' stay in Y'; X'' stay in Y''"
+  #    pattern. AI loves three-clause parallelism. Looks for repeated verb
+  #    three times in one line with semicolons.
+  if grep -nE '([A-Za-z]+) [a-z]+ in [^;]+; [A-Za-z]+ \1 [a-z]+ in [^;]+; [A-Za-z]+ \1 [a-z]+ in' "$file" > /dev/null; then
+    grep -nE '([A-Za-z]+) [a-z]+ in [^;]+; [A-Za-z]+ \1 [a-z]+ in [^;]+; [A-Za-z]+ \1 [a-z]+ in' "$file"
+    echo "FAIL: $file has triple-parallel 'X verbs in Y; X' verbs in Y'; …' construction"
+    fail=1
+  fi
+
+  # 10. Triple negation "It does NOT X, it does NOT Y, it does NOT Z" pattern.
+  if grep -nEi 'does \*?\*?not\*?\*? [^.]+\. (it|It) does \*?\*?not\*?\*? [^.]+\. (it|It) does \*?\*?not\*?\*?' "$file" > /dev/null; then
+    grep -nEi 'does \*?\*?not\*?\*? [^.]+\. (it|It) does \*?\*?not\*?\*? [^.]+\. (it|It) does \*?\*?not\*?\*?' "$file"
+    echo "FAIL: $file has triple-negation 'It does not X. It does not Y. It does not Z' construction"
+    fail=1
+  fi
+
+  # 11. List-of-three "no X, no Y, no Z" inside parentheses.
+  if grep -nE '\(no [a-z-]+, no [a-z-]+, no [a-z-]+\)' "$file" > /dev/null; then
+    grep -nE '\(no [a-z-]+, no [a-z-]+, no [a-z-]+\)' "$file"
+    echo "FAIL: $file has list-of-three '(no X, no Y, no Z)' construction"
+    fail=1
+  fi
+
+  # 12. "Reviewers copy this … workpapers" / "verbatim, not paraphrased"
+  #     pompous audit-evidence framing. A draft doc cannot represent itself
+  #     as a verbatim regulator-citation source. If a citation table needs
+  #     to claim verbatim accuracy, the doc must back it with a verification
+  #     trail; until then, the table is indicative.
+  if grep -nEi '(copy [^.]{0,40}workpapers|verbatim, not paraphrased|cite[^.]{0,40}verbatim)' "$file" > /dev/null; then
+    grep -nEi '(copy [^.]{0,40}workpapers|verbatim, not paraphrased|cite[^.]{0,40}verbatim)' "$file"
+    echo "FAIL: $file claims verbatim regulator-citation accuracy without a verification trail"
+    fail=1
+  fi
+
+  # 13. "is the only" / "is unique in" superlatives without measurable
+  #     evidence in the same sentence. Match the "X is the only Y" /
+  #     "X is unique among Y" patterns.
+  if grep -nEi '\bis (the only|unique (among|in)) [a-z]+\b' "$file" > /dev/null; then
+    grep -nEi '\bis (the only|unique (among|in)) [a-z]+\b' "$file"
+    echo "FAIL: $file uses superlative 'is the only / unique' without measurable referent"
+    fail=1
+  fi
+
+  # 14. Naming-denylist check. The architecture set states facts, never the
+  #     research path that produced them. The denied-term pattern is supplied
+  #     out-of-band via the LEXICON_DENYLIST environment variable (an
+  #     extended-regex, case-insensitive). When it is unset, this sub-check
+  #     is skipped with a notice. Matches are redacted to file:line only —
+  #     the matched text is never echoed.
+  if [ -n "${LEXICON_DENYLIST:-}" ]; then
+    if grep -nEi "$LEXICON_DENYLIST" "$file" > /dev/null; then
+      grep -nEi "$LEXICON_DENYLIST" "$file" | cut -d: -f1 | sort -u \
+        | while IFS= read -r ln; do echo "$file:$ln"; done
+      echo "FAIL: $file — denied term found"
+      fail=1
+    fi
+  else
+    echo "notice: LEXICON_DENYLIST unset — naming-denylist sub-check skipped"
+  fi
+
+  # 15. "bank" as the framing subject, not a named example. The default
+  #     audience term is "regulated enterprise"; a bank is allowed only as
+  #     one named example (e.g. "tier-1 US or EU bank"). Framing tells —
+  #     a bank as the sentence's subject, possessive, or an adjective —
+  #     widen wrongly: "the bank already runs", "a bank's machinery",
+  #     "targets banks", "bank-required", "bank-grade", "bank InfoSec/CISO".
+  #     The example-allowlist file carries the lines that legitimately name
+  #     a bank as an example; everything else fails.
+  if grep -nEiw 'bank|banks|banking' "$file" \
+       | grep -vEi 'tier-1 (us or eu )?bank|tier-1 banks|US or EU bank|retail-banking|banking convention|banking-vendor convention|named example.*bank|bank[,.) ]+(for example|e\.g\.|as one|as the named)' \
+       | grep -nEi "bank's|\bthe bank\b|\ba bank\b|targets? banks|bank-(required|grade|specific|facing|side)|bank (infosec|ciso|reviewer|procurement|architect|auditor)" > /dev/null; then
+    grep -nEi "bank's|\bthe bank\b|\ba bank\b|targets? banks|bank-(required|grade|specific|facing|side)|bank (infosec|ciso|reviewer|procurement|architect|auditor)" "$file" \
+      | grep -vEi 'tier-1 (us or eu )?bank|tier-1 banks|US or EU bank|retail-banking|banking convention|banking-vendor convention'
+    echo "FAIL: $file frames the audience as 'bank' — use 'regulated enterprise'; a bank is allowed only as a named example (tier-1 US/EU bank)"
+    fail=1
+  fi
+
+  # 16. SAML as a platform identity surface. OCU's identity surface is
+  #     OIDC-only; a SAML-only customer IdP federates in through Dex or
+  #     Keycloak, never an OCU SAML endpoint. Any SAML mention must be in a
+  #     federation/legacy-fallback clause, not asserted as something OCU
+  #     speaks. Allowlist the federation phrasing; everything else fails.
+  if grep -nEi '\bSAML\b' "$file" \
+       | grep -vEi 'SAML-only (customer )?(idp|pam)|federates? in through (dex|keycloak)|never an OCU SAML|through Dex or Keycloak' > /dev/null; then
+    grep -nEi '\bSAML\b' "$file" \
+      | grep -vEi 'SAML-only (customer )?(idp|pam)|federates? in through (dex|keycloak)|never an OCU SAML|through Dex or Keycloak'
+    echo "FAIL: $file asserts SAML as a platform surface — OCU is OIDC-only; a SAML-only IdP federates in via Dex/Keycloak"
+    fail=1
+  fi
+}
+
+for f in "${files[@]}"; do
+  [[ -f "$f" ]] || continue
+  lines=$(wc -l < "$f" | tr -d ' ')
+  check "$f" "$lines"
+done
+
+if (( fail )); then
+  echo
+  echo "Hint: see CLAUDE.md 'Documentation discipline' for the banned patterns."
+  exit 1
+fi
+
+echo "ai-slop-detector: OK"

package/scripts/docs-lint/architecture-tree-whitelist.sh

@@ -0,0 +1,131 @@
+#!/usr/bin/env bash
+# SPDX-License-Identifier: FSL-1.1-Apache-2.0
+# Copyright (c) 2025 Open Computer Use Contributors
+#
+# architecture-tree-whitelist — fail when an unexpected file appears under
+# `docs/architecture/`. Each directory has a known set of allowed files and
+# filename patterns. Anything outside the whitelist signals that:
+#
+#   - someone wrote a verifier snapshot, scratch note, or AI artifact into
+#     the architecture set (drift the moment the next pass runs), OR
+#   - someone added a new directory without following PROCESS.md, OR
+#   - a typo / wrong location for an otherwise legitimate file.
+#
+# Each new component / ADR / mapping that needs a new file shape must:
+#   1. follow PROCESS.md "Adding a <thing>",
+#   2. update this whitelist in the same PR.
+#
+# Run from repo root: scripts/docs-lint/architecture-tree-whitelist.sh
+
+set -euo pipefail
+
+ROOT="$(git rev-parse --show-toplevel)"
+cd "$ROOT"
+
+if [ ! -d docs/architecture ]; then
+  echo "architecture-tree-whitelist: docs/architecture/ does not exist, nothing to check"
+  exit 0
+fi
+
+# Per-directory allow-list. `*` is a glob, not regex; it matches anything
+# except `/` (so `compliance/*-mapping.md` does not match `compliance/sub/x.md`).
+ALLOWED=(
+  # Top-level architecture-set roots.
+  "README.md"
+  "MANIFESTO.md"
+  "glossary.md"
+  "PROCESS.md"
+  "primitives-backlog.md"
+
+  # Top-level numbered cross-cutting artifacts (scope cuts across the whole
+  # tree, cited by every component spec — e.g. trust boundaries, C4 context,
+  # deployment topologies). Per PROCESS.md, these live at the top level rather
+  # than under `manifesto/` or `components/`.
+  "[0-9][0-9]-*.md"
+
+  # ADRs.
+  "adr/README.md"
+  "adr/0000-template.md"
+  "adr/[0-9][0-9][0-9][0-9]-*.md"
+
+  # Component specs.
+  "components/README.md"
+  "components/0000-template.md"
+  "components/[0-9][0-9]-*.md"
+
+  # Manifesto sections (one numbered file per section).
+  "manifesto/README.md"
+  "manifesto/[0-9][0-9]-*.md"
+
+  # Compliance — only the cross-framework matrix and per-framework mappings.
+  "compliance/README.md"
+  "compliance/controls-matrix.md"
+  "compliance/*-mapping.md"
+  "compliance/sub-processors.md"
+
+  # Diagrams — sources only. PNG / SVG / JPG forbidden (CLAUDE.md §Diagrams).
+  "diagrams/README.md"
+  "diagrams/*.mmd"
+  "diagrams/*.d2"
+  "diagrams/*.puml"
+
+  # Threat models — Threagile / pytm YAML.
+  "threat-model/README.md"
+  "threat-model/*.yaml"
+  "threat-model/*.yml"
+
+  # Contracts — OpenAPI / AsyncAPI / Protobuf / MCP schema.
+  "contracts/README.md"
+  "contracts/*.yaml"
+  "contracts/*.yml"
+  "contracts/*.json"
+  "contracts/*.proto"
+
+  # gitkeep markers for empty scaffold directories. The `?` is a literal
+  # filename character set by the glob translator; here we match exactly
+  # ".gitkeep" anywhere one directory deep under docs/architecture/.
+  "*/.gitkeep"
+)
+
+python3 - "${ALLOWED[@]}" <<'PY'
+import fnmatch, pathlib, sys
+
+allowed_globs = sys.argv[1:]
+root = pathlib.Path("docs/architecture")
+
+def match_pattern(rel: str, pattern: str) -> bool:
+    """Segment-aware glob match. `*` never crosses `/`.
+
+    Plain `fnmatch.fnmatchcase` treats `/` as a normal character, so
+    `compliance/*-mapping.md` would silently accept
+    `compliance/sub/evil-mapping.md`. We split on `/` and require equal
+    depth + per-segment match instead.
+    """
+    rel_parts = rel.split("/")
+    pat_parts = pattern.split("/")
+    if len(rel_parts) != len(pat_parts):
+        return False
+    return all(fnmatch.fnmatchcase(r, p) for r, p in zip(rel_parts, pat_parts))
+
+fail = False
+for path in root.rglob("*"):
+    if not path.is_file():
+        continue
+    rel = path.relative_to(root).as_posix()
+    if not any(match_pattern(rel, g) for g in allowed_globs):
+        print(f"FAIL: docs/architecture/{rel} — file not on the whitelist")
+        fail = True
+
+if fail:
+    print("""
+Hint: every file under docs/architecture/ must match a whitelist entry in
+scripts/docs-lint/architecture-tree-whitelist.sh. If the file is legitimate
+(new component, new compliance mapping, new diagram), add the matching
+pattern to ALLOWED in the same PR. If it is a scratch note, verifier
+snapshot, or AI artifact — delete it. Process: docs/architecture/PROCESS.md
+and CLAUDE.md "Architecture content routing".
+""")
+    sys.exit(1)
+
+print("architecture-tree-whitelist: OK")
+PY

package/scripts/docs-lint/ascii-diagram-detector.sh

@@ -0,0 +1,58 @@
+#!/usr/bin/env bash
+# SPDX-License-Identifier: FSL-1.1-Apache-2.0
+# Copyright (c) 2025 Open Computer Use Contributors
+#
+# ASCII-diagram detector — blocks box-drawing characters in docs/architecture/.
+#
+# Per CLAUDE.md "Diagrams": Mermaid first; D2/PlantUML when needed; ASCII
+# diagrams are forbidden in docs/architecture/ (they don't render in browsers,
+# can't be linted for broken references, and signal AI-style ad-hoc artwork).
+#
+# Box-drawing Unicode ranges: U+2500–U+257F, plus heavy "═║╔╗╚╝╠╣╦╩╬" style.
+# Common ASCII fallbacks like `+--+` and `|  |` in tables are NOT flagged —
+# they're legitimate Markdown tables.
+#
+# Exits 1 if any box-drawing characters are found in docs/architecture/.
+
+set -euo pipefail
+
+ROOT="$(git rev-parse --show-toplevel)"
+cd "$ROOT"
+
+# Unicode box-drawing block: ─ │ ┌ ┐ └ ┘ ├ ┤ ┬ ┴ ┼ ═ ║ ╔ ╗ ╚ ╝ ╠ ╣ ╦ ╩ ╬ etc.
+pattern=$'[─-╿]'
+
+# Gather .md files under docs/architecture/.
+mapfile -t files < <(find docs/architecture -name '*.md' 2>/dev/null)
+
+if (( ${#files[@]} == 0 )); then
+  echo "ascii-diagram-detector: OK (no files to scan)"
+  exit 0
+fi
+
+# Use Python for reliable Unicode-range grep (macOS grep -P is limited).
+python3 - "${files[@]}" <<'PY'
+import re, sys
+pat = re.compile(r"[─-╿▀-▟]")
+fail = False
+for path in sys.argv[1:]:
+    try:
+        with open(path, encoding="utf-8") as f:
+            for i, line in enumerate(f, 1):
+                if pat.search(line):
+                    print(f"FAIL: {path}:{i}: Unicode box-drawing diagram detected")
+                    fail = True
+    except (OSError, UnicodeDecodeError):
+        continue
+sys.exit(1 if fail else 0)
+PY
+
+status=$?
+
+if (( status != 0 )); then
+  echo
+  echo "Hint: convert to Mermaid (committed alongside the doc as .mmd, or inline if ≤ 15 lines)."
+  exit 1
+fi
+
+echo "ascii-diagram-detector: OK"

package/scripts/docs-lint/front-matter-validator.sh

@@ -0,0 +1,97 @@
+#!/usr/bin/env bash
+# SPDX-License-Identifier: FSL-1.1-Apache-2.0
+# Copyright (c) 2025 Open Computer Use Contributors
+#
+# Front-matter validator — every doc under docs/architecture/ MUST carry the
+# four mandatory YAML fields per CLAUDE.md "Documentation discipline":
+#   status, last-reviewed (YYYY-MM-DD), owner, applies-to
+#
+# Also emits a non-blocking WARN if last-reviewed > 180 days old.
+#
+# Exits 1 if any required field is missing from any architecture doc.
+
+set -euo pipefail
+
+ROOT="$(git rev-parse --show-toplevel)"
+cd "$ROOT"
+
+fail=0
+today_epoch=$(date +%s)
+stale_threshold=$((180 * 24 * 3600))
+
+check_file() {
+  local file="$1"
+  python3 - "$file" "$today_epoch" "$stale_threshold" <<'PY'
+import re, sys, datetime as dt, pathlib
+
+path = pathlib.Path(sys.argv[1])
+today_epoch = int(sys.argv[2])
+stale_threshold = int(sys.argv[3])
+
+text = path.read_text(encoding="utf-8")
+
+# Strip leading HTML license comments (the SPDX header convention).
+stripped = re.sub(r'^(?:<!--.*?-->\s*\n)+', '', text, flags=re.DOTALL)
+
+if not stripped.startswith('---'):
+    print(f"FAIL: {path}: no YAML front-matter block")
+    sys.exit(1)
+
+m = re.match(r'^---\n(.*?)\n---', stripped, flags=re.DOTALL)
+if not m:
+    print(f"FAIL: {path}: front-matter block not closed with `---`")
+    sys.exit(1)
+
+body = m.group(1)
+fields = {}
+for line in body.splitlines():
+    line = line.rstrip()
+    if not line or line.startswith('#'):
+        continue
+    if ':' not in line or line.startswith((' ', '\t', '-')):
+        continue
+    key, _, val = line.partition(':')
+    fields[key.strip()] = val.strip().strip('"').strip("'")
+
+required = ["status", "last-reviewed", "owner", "applies-to"]
+missing = [k for k in required if k not in fields or not fields[k]]
+if missing:
+    print(f"FAIL: {path}: missing front-matter fields: {', '.join(missing)}")
+    sys.exit(1)
+
+# Accept the literal placeholder YYYY-MM-DD only in template files.
+last_reviewed = fields["last-reviewed"]
+if last_reviewed == "YYYY-MM-DD":
+    if "template" not in path.name.lower():
+        print(f"FAIL: {path}: last-reviewed is placeholder 'YYYY-MM-DD' in a non-template file")
+        sys.exit(1)
+    sys.exit(0)
+
+try:
+    parsed = dt.date.fromisoformat(last_reviewed)
+except ValueError:
+    print(f"FAIL: {path}: last-reviewed '{last_reviewed}' is not YYYY-MM-DD")
+    sys.exit(1)
+
+age = today_epoch - int(dt.datetime.combine(parsed, dt.time()).timestamp())
+if age > stale_threshold:
+    print(f"WARN: {path}: last-reviewed {last_reviewed} is over 180 days old")
+    # Non-blocking — exit 0.
+
+sys.exit(0)
+PY
+}
+
+while IFS= read -r -d '' f; do
+  if ! check_file "$f"; then
+    fail=1
+  fi
+done < <(find docs/architecture -name '*.md' -print0 2>/dev/null)
+
+if (( fail )); then
+  echo
+  echo "Hint: add YAML front-matter with status, last-reviewed (YYYY-MM-DD), owner, applies-to."
+  exit 1
+fi
+
+echo "front-matter-validator: OK"