feat(shared/lock): add doc with docs

Author: rudraditya21

docs/scripts/shared/lock/doc.md

@@ -0,0 +1,27 @@
+# doc.sh
+
+## Purpose
+Generate quick-reference documentation for the shared lock module.
+
+## Location
+`shared/lock/doc.sh`
+
+## Preconditions
+- Required tools: `bash`
+- Required permissions: write permission when using `--output`
+- Required environment variables: none
+
+## Arguments
+| Flag | Required | Default | Description |
+|------|----------|---------|-------------|
+| `--format FORMAT` | No | `markdown` | Output format: `markdown` or `text` |
+| `--output PATH` | No | stdout | Write rendered content to file |
+
+## Usage
+```bash
+shared/lock/doc.sh
+shared/lock/doc.sh --format text --output /tmp/lock-doc.txt
+```
+
+## Output
+- Exit codes: `0` success, `2` invalid args.

shared/lock/doc.sh

@@ -0,0 +1,92 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+usage() {
+  cat << 'USAGE'
+Usage: doc.sh [OPTIONS]
+
+Generate quick reference docs for the lock shared module.
+
+Options:
+  --format FORMAT    markdown|text (default: markdown)
+  --output PATH      Write to file instead of stdout
+  -h, --help         Show help
+USAGE
+}
+
+die() {
+  printf 'ERROR: %s\n' "$*" >&2
+  exit 2
+}
+
+format="markdown"
+output=""
+
+while (($#)); do
+  case "$1" in
+    --format)
+      shift
+      (($#)) || die "--format requires a value"
+      format="$1"
+      ;;
+    --output)
+      shift
+      (($#)) || die "--output requires a value"
+      output="$1"
+      ;;
+    -h|--help)
+      usage
+      exit 0
+      ;;
+    *)
+      die "unknown option: $1"
+      ;;
+  esac
+  shift
+done
+
+render_markdown() {
+  cat << 'MD'
+# shared/lock Module
+
+## Scripts
+- `shared/lock/example.sh`: wraps `shared/safety/file-lock.sh` with example defaults
+- `shared/lock/test.sh`: validates lock acquisition, contention timeout, and stale lock cleanup
+- `shared/lock/doc.sh`: generates this quick reference
+
+## Core Dependencies
+- `shared/safety/file-lock.sh`
+MD
+}
+
+render_text() {
+  cat << 'TXT'
+shared/lock module
+
+scripts:
+- shared/lock/example.sh: lock wrapper example
+- shared/lock/test.sh: smoke tests for lock behavior
+- shared/lock/doc.sh: quick reference generator
+
+dependencies:
+- shared/safety/file-lock.sh
+TXT
+}
+
+case "$format" in
+  markdown)
+    rendered="$(render_markdown)"
+    ;;
+  text)
+    rendered="$(render_text)"
+    ;;
+  *)
+    die "invalid --format: $format"
+    ;;
+esac
+
+if [[ -n "$output" ]]; then
+  printf '%s\n' "$rendered" > "$output"
+else
+  printf '%s\n' "$rendered"
+fi