docs(guides): improve Context7 hooks setup guidance

Co-authored-by: factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com>

Author: factory-ben

docs/docs.json

@@ -227,7 +227,8 @@
             "group": "Building",
             "pages": [
               "guides/building/droid-exec-tutorial",
-              "guides/building/droid-vps-setup"
+              "guides/building/droid-vps-setup",
+              "guides/building/context7-hooks"
             ]
           }
         ]

docs/guides/building/context7-hooks.mdx

@@ -0,0 +1,301 @@
+---
+title: "Context7 Hooks: Token Caps + Auto Archive"
+description: "Cap the number of tokens retrieved by Context7"
+---
+
+<Note>
+  Context7 already ships in Factory’s MCP registry. Once you authenticate it, you can plug in custom hooks to keep documentation pulls lightweight, logged, and repeatable.
+</Note>
+
+<Tip>
+  New to hooks? Start with [Get started with hooks](/cli/configuration/hooks-guide) for a walkthrough of the hooks UI and configuration model, then come back here to plug in the Context7-specific scripts.
+</Tip>
+
+## Prerequisites
+
+- Factory CLI installed
+- Context7 account + API token for MCP auth
+- `jq` installed (`brew install jq` on macOS)
+- A text editor—everything below builds the scripts from scratch
+- Hooks feature enabled (run `/settings`, toggle **Hooks** to **Enabled** so the `/hooks` command is available)
+
+## Step 1 · Authenticate the Context7 MCP connector
+
+<Steps>
+  <Step title="Start the auth flow">
+    Run the `/mcp` slash command to open the MCP manager. From the **Registry** list, select the `context7` entry to add it, then in the server detail view choose **Authenticate**. Follow the browser prompt; credentials are saved to `~/.factory/mcp-oauth.json`.
+  </Step>
+  <Step title="Verify connectivity">
+    Open `/mcp` again, select the `context7` server, and confirm it shows as enabled and authenticated (you should be able to view its tools, including `get-library-docs`). If not, run **Authenticate** again.
+  </Step>
+</Steps>
+
+## Step 2 · Create the hook scripts
+
+You can either have droid generate the scripts for you, or use a copy‑paste template.
+
+### Option A · Ask droid to generate the scripts
+
+If you want hooks in a project, in your project root, start a droid session and give it a prompt like:
+
+```text
+In this repo, create ~/.factory/hooks/context7_token_limiter.sh and ~/.factory/hooks/context7_archive.sh.
+The first should be a PreToolUse hook that enforces a MAX_TOKENS limit (3000) on the tool context7___get-library-docs.
+The second should archive every successful response as Markdown with YAML frontmatter into ${FACTORY_PROJECT_DIR:-$PWD}/context7-archive.
+Use jq and follow the hooks JSON input/output contracts from the hooks reference docs.
+```
+
+Review droid’s proposal, tweak as needed, then save the scripts under `~/.factory/hooks/` and make them executable:
+
+```bash
+chmod +x ~/.factory/hooks/context7_token_limiter.sh ~/.factory/hooks/context7_archive.sh
+```
+
+### Option B · Use the reference template
+
+Ensure the `~/.factory/hooks` directory exists, then create these two files.
+
+**`~/.factory/hooks/context7_token_limiter.sh`**
+
+```bash
+#!/usr/bin/env bash
+set -euo pipefail
+umask 077
+
+MAX_TOKENS="${MAX_TOKENS:-3000}"
+LOG_FILE="${LOG_FILE:-$HOME/.factory/hooks/context7.log}"
+
+ts() { date -u +"%Y-%m-%dT%H:%M:%SZ"; }
+log() {
+  mkdir -p "$(dirname "$LOG_FILE")" 2>/dev/null || true
+  printf "[%s] %s\n" "$(ts)" "$1" >> "$LOG_FILE" 2>/dev/null || true
+}
+
+if ! command -v jq >/dev/null 2>&1; then
+  printf "Warning: jq not found. Allowing tool call.\n" >&2
+  exit 0
+fi
+
+payload="$(cat)"
+tool_name="$(printf "%s" "$payload" | jq -r '.tool_name // empty' 2>/dev/null || printf "")"
+
+if [[ "$tool_name" != "context7___get-library-docs" ]]; then
+  exit 0
+fi
+
+tokens="$(printf "%s" "$payload" | jq -r 'if (.tool_input.tokens? // null) == null then "" else (.tool_input.tokens | tonumber | floor) end' 2>/dev/null || printf "")"
+
+if [[ -z "$tokens" ]]; then
+  exit 0
+fi
+
+if ! [[ "$tokens" =~ ^[0-9]+$ ]]; then
+  printf "Warning: invalid tokens parameter: %s\n" "$tokens" >&2
+  exit 1
+fi
+
+if (( tokens > MAX_TOKENS )); then
+  log "BLOCKED: Context7 call with $tokens tokens (limit: $MAX_TOKENS)"
+  cat >&2 <<EOWARN
+Context7 token limit exceeded: $tokens > $MAX_TOKENS
+
+Keep queries iterative so each pull stays focused. Reduce the topic scope and re-run at <= $MAX_TOKENS tokens.
+EOWARN
+  exit 2
+fi
+
+exit 0
+```
+
+**`~/.factory/hooks/context7_archive.sh`**
+
+```bash
+#!/usr/bin/env bash
+set -euo pipefail
+umask 077
+
+ARCHIVE_DIR="${ARCHIVE_DIR:-${FACTORY_PROJECT_DIR:-$PWD}/context7-archive}"
+MAX_TOPIC_LENGTH=${MAX_TOPIC_LENGTH:-50}
+DEBUG_LOG="$ARCHIVE_DIR/hook-debug.log"
+RAW_JSON="${RAW_JSON:-0}"
+
+debug() {
+  if [[ "${DEBUG:-0}" == "1" ]]; then
+    mkdir -p "$ARCHIVE_DIR"
+    echo "[$(date -u +"%Y-%m-%dT%H:%M:%SZ")] $*" >> "$DEBUG_LOG"
+  fi
+}
+
+if ! command -v jq >/dev/null 2>&1; then
+  echo "Warning: jq not found. Context7 archive hook disabled." >&2
+  exit 0
+fi
+
+payload="$(cat)"
+tool_name="$(printf "%s" "$payload" | jq -r '.tool_name // empty' 2>/dev/null || printf "")"
+
+if [[ "$tool_name" != "context7___get-library-docs" ]]; then
+  debug "Skipping non-Context7 tool"
+  exit 0
+fi
+
+if [[ "$RAW_JSON" == "1" ]]; then
+  results="$(printf "%s" "$payload" | jq -c '.tool_response' 2>/dev/null || printf "")"
+else
+  results="$(printf "%s" "$payload" | jq -r '.tool_response | if type == "string" then . else (.text // tojson) end' 2>/dev/null || printf "")"
+fi
+
+if [[ -z "$results" || "$results" == "null" ]]; then
+  debug "No results to archive"
+  exit 0
+fi
+
+library_id="$(printf "%s" "$payload" | jq -r '.tool_input.context7CompatibleLibraryID // "unknown-library"' 2>/dev/null || printf "unknown-library")"
+topic="$(printf "%s" "$payload" | jq -r '.tool_input.topic // "untitled"' 2>/dev/null || printf "untitled")"
+
+project_name="$(basename "${FACTORY_PROJECT_DIR:-$PWD}" | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9-]/-/g')"
+library_slug="$(printf "%s" "$library_id" | sed 's|^/||' | cut -d/ -f2 | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9-]/-/g')"
+library_slug="${library_slug:-unknown}"
+topic_slug="$(printf "%s" "$topic" | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9 -]//g' | sed 's/  */-/g' | sed 's/^-//' | sed 's/-$//')"
+topic_slug="${topic_slug:-untitled}"
+
+if [[ ${#topic_slug} -gt $MAX_TOPIC_LENGTH ]]; then
+  topic_slug="${topic_slug:0:$MAX_TOPIC_LENGTH}"
+  topic_slug="${topic_slug%-*}"
+fi
+
+mkdir -p "$ARCHIVE_DIR"
+stamp="$(date +"%Y%m%d")"
+base="${stamp}_${project_name}_${library_slug}_${topic_slug}"
+file="$ARCHIVE_DIR/${base}.md"
+counter=1
+while [[ -f "$file" ]]; do
+  file="$ARCHIVE_DIR/${base}-${counter}.md"
+  ((counter++))
+done
+
+cat > "$file" <<EOC
+---
+query_date: $(date -u +"%Y-%m-%d %H:%M:%S UTC")
+library: $library_id
+topic: $topic
+project: $project_name
+tool: $tool_name
+---
+
+# Context7 Query: $topic
+
+$results
+EOC
+
+debug "Archived to $file"
+exit 0
+```
+
+Then make both scripts executable:
+
+```bash
+chmod +x ~/.factory/hooks/context7_token_limiter.sh ~/.factory/hooks/context7_archive.sh
+```
+
+<Note>
+  The matcher should target the LLM tool name `context7___get-library-docs`. If you’re unsure, inspect `~/.factory/hooks/context7.log` (written by the limiter) or open the latest transcript file (see the `transcript_path` field, typically under `~/.factory/projects/...`) to inspect the `tool_name` value.
+</Note>
+
+## Step 3 · Token limiter (PreToolUse)
+
+- **Hook file:** `~/.factory/hooks/context7_token_limiter.sh`
+- **Purpose:** Block any `context7___get-library-docs` call that requests more than 3,000 tokens.
+- **Useful env vars:**
+
+```bash
+export MAX_TOKENS=3000
+export LOG_FILE="$HOME/.factory/hooks/context7.log"  # Optional auditing
+```
+
+When the script exits with code 2, Factory halts the tool call and surfaces the warning text to the assistant.
+
+## Step 4 · Archive writer (PostToolUse)
+
+- **Hook file:** `~/.factory/hooks/context7_archive.sh`
+- **Purpose:** Save every successful Context7 response as Markdown in `${FACTORY_PROJECT_DIR}/context7-archive` (falls back to your current repo if the env var is unset).
+- **Useful env vars:**
+
+```bash
+export DEBUG=1                           # Verbose logging to hook-debug.log
+export ARCHIVE_DIR="$HOME/context7-history"  # Optional custom location
+export RAW_JSON=1                        # Store raw JSON payloads instead of rendered text
+```
+
+Each file includes YAML frontmatter so you can grep or index entries later (e.g., `20251114_myapp_nextjs_server-actions.md`).
+
+## Step 5 · Register the hooks
+
+You can register these hooks either through the `/hooks` UI (recommended) or by editing `~/.factory/settings.json` directly.
+
+### Option A - Use the Hooks UI
+
+1. Run `/settings` and make sure **Hooks** is set to **Enabled**.
+2. Run `/hooks`, select the **PreToolUse** event, and add a matcher `context7___get-library-docs`. Hit enter to save.
+3. Add a `command`: `~/.factory/hooks/context7_token_limiter.sh`, and store it in **User settings**.
+4. Repeat for **PostToolUse**, matcher `context7___get-library-docs`, command `~/.factory/hooks/context7_archive.sh`.
+
+### Option B - Edit settings JSON
+
+Open `~/.factory/settings.json` and add a `hooks` block like this (merging with any existing hooks):
+
+```jsonc
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "context7___get-library-docs",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "~/.factory/hooks/context7_token_limiter.sh",
+            "timeout": 5000
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "context7___get-library-docs",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "~/.factory/hooks/context7_archive.sh",
+            "timeout": 5000
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+Using the exact LLM tool name `context7___get-library-docs` ensures you only target the Context7 docs fetch tool. You can also use regex matchers (see [Hooks reference](/reference/hooks-reference)) if you need to match multiple Context7 tools.
+
+Restart Factory (or reopen your session) after editing your hooks configuration.
+
+## Step 6 · Test the workflow
+
+<Steps>
+  <Step title="Limiter">
+    Ask Context7 for something intentionally huge, e.g. “Pull the entire Factory documentation with context7 mcp". The hook should block it at 3,000 tokens. (Factory already has a local codemap for its docs; this request is purely for testing.)
+  </Step>
+  <Step title="Archive">
+    Run a normal Context7 request. Confirm `context7-archive/` now contains a timestamped Markdown file with the query results.
+  </Step>
+</Steps>
+
+## Troubleshooting & customization
+
+- **Matcher typos:** If the hooks never run, double-check the matcher value against `context7___get-library-docs`. One missing underscore is enough to break it.
+- **Missing `jq`:** Install it with `brew install jq` (macOS) or your distro’s package manager.
+- **Permissions:** Ensure every script in `~/.factory/hooks` is executable (`chmod +x ~/.factory/hooks/*`).
+- **Archive clutter:** Add `context7-archive/` to `.gitignore` if you don’t plan to commit the saved docs.
+- **Timeouts:** Increase the `timeout` field in `hooks.json` if you routinely archive very large responses.
+
+With these two hooks in place, every Context7 pull stays within a predictable token budget and automatically lands in a searchable knowledge base.