BUILD PR: add minimal usage doc for shared extraction guard.

Author: DavidQ

docs/dev/CODEX_COMMANDS.md

@@ -1,8 +1,8 @@
 MODEL: GPT-5.3-codex
 REASONING: high
 COMMAND:
-Execute docs/pr/BUILD_PR_SHARED_EXTRACTION_22_ADD_GUARD_RUN_SCRIPT.md exactly.
+Execute docs/pr/BUILD_PR_SHARED_EXTRACTION_23_GUARD_DOC_MINIMAL_USAGE.md exactly.
 Create only:
-- tools/dev/runSharedExtractionGuard.sh
+- docs/dev/SHARED_EXTRACTION_GUARD_USAGE.md
 Do not expand scope.
-Package delta to <project folder>/tmp/BUILD_PR_SHARED_EXTRACTION_22_ADD_GUARD_RUN_SCRIPT_delta.zip
+Package delta to <project folder>/tmp/BUILD_PR_SHARED_EXTRACTION_23_GUARD_DOC_MINIMAL_USAGE_delta.zip

docs/dev/COMMIT_COMMENT.txt

@@ -1 +1 @@
-BUILD PR: add simple script to run shared extraction guard.
+BUILD PR: add minimal usage doc for shared extraction guard.

docs/dev/SHARED_EXTRACTION_GUARD_USAGE.md

@@ -0,0 +1,19 @@
+# SHARED_EXTRACTION_GUARD_USAGE
+
+## Run
+- `node tools/dev/checkSharedExtractionGuard.mjs`
+- `npm run check:shared-extraction-guard` (if present)
+- `./tools/dev/runSharedExtractionGuard.sh`
+
+## What It Checks
+- duplicate helpers (`asFiniteNumber`, `asPositiveInteger`, `isPlainObject`)
+- bad shared imports (fragile relative shared paths)
+- alias usage (`@shared/`)
+
+## What Failure Means
+- One or more files violate shared-extraction guard rules and must be corrected before proceeding.
+
+## Fix Violations
+- remove local duplicate helper definitions
+- replace disallowed shared import paths with approved paths
+- remove `@shared/` alias imports and use approved relative imports

docs/dev/reports/change_summary.txt

@@ -1 +1 @@
-Adds simple guard runner script.
+Adds guard usage documentation.

docs/dev/reports/validation_checklist.txt

@@ -1 +1 @@
-script added correctly
+doc added correctly

docs/pr/BUILD_PR_SHARED_EXTRACTION_23_GUARD_DOC_MINIMAL_USAGE.md

@@ -0,0 +1,36 @@
+# BUILD_PR_SHARED_EXTRACTION_23_GUARD_DOC_MINIMAL_USAGE
+
+## Purpose
+Add minimal documentation describing how to run and interpret the shared-extraction guard.
+
+## Single PR Purpose
+Create one doc file:
+
+docs/dev/SHARED_EXTRACTION_GUARD_USAGE.md
+
+## Exact Files Allowed
+1. docs/dev/SHARED_EXTRACTION_GUARD_USAGE.md (new file)
+
+## Exact Content
+
+Include:
+- how to run:
+  - node tools/dev/checkSharedExtractionGuard.mjs
+  - npm run check:shared-extraction-guard (if present)
+  - ./tools/dev/runSharedExtractionGuard.sh
+- what it checks:
+  - duplicate helpers
+  - bad shared imports
+  - alias usage
+- what failure means
+- how to fix violations (short bullet list)
+
+## Rules
+- no other files
+- no config changes
+- no logic changes
+
+## Validation
+1. file exists
+2. content matches scope
+3. no other files changed