---
phase: 04-docs
plan: 03
type: execute
wave: 2
depends_on: ["04-01"]
files_modified:
  - docs/scanners/pii.md
  - docs/scanners/topic.md
  - docs/scanners/toxicity.md
  - docs/scanners/cyber.md
  - docs/scanners/jailbreak.md
autonomous: false

must_haves:
  truths:
    - "Every scanner has a dedicated reference page with labels, actions, conditions, and working code examples"
    - "PIIScanner page lists all 47 canonical labels and 5 bundle shortcuts with collapsible detail blocks"
    - "Each scanner page has a 'When to Use This' section explaining what it protects against"
    - "Each scanner page shows both scan_input and scan_output examples"
    - "TC scanner pages list their label enums with descriptions of what each detects"
  artifacts:
    - path: "docs/scanners/pii.md"
      provides: "PIIScanner reference with 53-label enum, 5 bundles, overrides, full examples"
      min_lines: 150
    - path: "docs/scanners/topic.md"
      provides: "TopicScanner reference with 30 labels, use cases, examples"
      min_lines: 80
    - path: "docs/scanners/toxicity.md"
      provides: "ToxicityScanner reference with 4 labels, use cases, examples"
      min_lines: 80
    - path: "docs/scanners/cyber.md"
      provides: "CyberScanner reference with 11 labels, use cases, examples"
      min_lines: 80
    - path: "docs/scanners/jailbreak.md"
      provides: "JailbreakScanner reference with 2 labels, forward-compat note, examples"
      min_lines: 60
  key_links:
    - from: "docs/scanners/pii.md"
      to: "docs/concepts.md"
      via: "Action/Condition cross-reference"
      pattern: "concepts"
    - from: "docs/scanners/pii.md"
      to: "docs/deanonymize.md"
      via: "Deanonymize workflow link"
      pattern: "deanonymize"
    - from: "docs/scanners/jailbreak.md"
      to: "docs/concepts.md"
      via: "Action/Condition cross-reference"
      pattern: "concepts"
---

<objective>
Write all five scanner reference pages following a consistent structure: PIIScanner (with bundles and overrides), TopicScanner, ToxicityScanner, CyberScanner, and JailbreakScanner.

Purpose: Scanner reference pages are the core of the docs. Developers will land here when integrating specific scanners. Each page must be self-sufficient with labels, examples, and parameters.
Output: Five complete scanner reference pages following the template from RESEARCH.md Pattern 5, with all label enums documented and working code examples.
</objective>

<execution_context>
@/Users/shalev/.claude/get-shit-done/workflows/execute-plan.md
@/Users/shalev/.claude/get-shit-done/templates/summary.md
</execution_context>

<context>
@.planning/PROJECT.md
@.planning/ROADMAP.md
@.planning/STATE.md
@.planning/phases/04-docs/04-CONTEXT.md
@.planning/phases/04-docs/04-RESEARCH.md
@src/meshulash_guard/scanners/pii.py
@src/meshulash_guard/scanners/topic.py
@src/meshulash_guard/scanners/toxicity.py
@src/meshulash_guard/scanners/cyber.py
@src/meshulash_guard/scanners/jailbreak.py
</context>

<tasks>

<task type="auto">
  <name>Task 1: Write PIIScanner reference page</name>
  <files>docs/scanners/pii.md</files>
  <action>
Write `docs/scanners/pii.md` following the scanner page structure from RESEARCH.md Pattern 5. PIIScanner is the heaviest page because of 53 labels, 5 bundles, and per-label overrides.

**Page structure:**

1. **# PIIScanner** -- one-line description: "Detect and redact personally identifiable information in text."

2. **## When to Use This** -- 1-2 paragraphs:
   - Protecting user prompts containing names, emails, phone numbers, SSNs, credit cards, API keys, etc.
   - Use cases: customer support chatbots, document analysis, any LLM app processing user input that might contain PII
   - Mention the deanonymize workflow for when you need originals back after LLM processing (link to deanonymize.md)

3. **## Quick Example** -- Self-contained code:
   - Import Guard, Action, PIIScanner, PIILabel
   - Guard(api_key=..., tenant_id=...)
   - PIIScanner with [PIILabel.EMAIL_ADDRESS, PIILabel.PHONE_NUMBER], action=Action.REPLACE
   - Realistic input: "My email is sarah@company.com and phone is 555-0123"
   - Show expected output: status="secured", processed_text with placeholders

4. **## Labels** section with two subsections:

   **### Individual Labels** -- Table: Label | What It Detects
   List ALL 47 canonical PIILabel members. Use the exact enum member names from RESEARCH.md (lines 507). For "What It Detects", provide a brief description:
   - PERSON_NAME: Full names of individuals
   - NATIONAL_ID: National identification numbers (SSN, etc.)
   - DRIVER_LICENSE: Driver's license numbers
   - USERNAME: Usernames and handles
   - TAX_NUMBER: Tax identification numbers
   - ACCOUNT_ID: Account identifiers
   - BUSINESS_ID: Business identification numbers
   - EMAIL_ADDRESS: Email addresses
   - PHONE_NUMBER: Phone numbers
   - STREET_ADDRESS: Physical street addresses
   - CITY: City names
   - COUNTY: County names
   - STATE: State/province names
   - COUNTRY: Country names
   - POSTAL_CODE: Postal/ZIP codes
   - IP_ADDRESS: IPv4 and IPv6 addresses
   - MAC_ADDRESS: Hardware MAC addresses
   - URL: Web URLs
   - CREDIT_CARD: Credit/debit card numbers
   - IBAN: International bank account numbers
   - BANK_ACCOUNT: Bank account numbers
   - ROUTING_NUMBER: Bank routing numbers
   - CRYPTO_ADDRESS: Cryptocurrency wallet addresses
   - PASSWORD: Password strings
   - SECRET_KEY: Secret/signing keys
   - ACCESS_TOKEN: Access tokens
   - PRIVATE_KEY: Private keys (RSA, SSH, etc.)
   - CONNECTION_STRING: Database connection strings
   - AWS_ACCESS_KEY: AWS access key IDs
   - AWS_SECRET_KEY: AWS secret access keys
   - GCP_API_KEY: Google Cloud API keys
   - GCP_SERVICE_ACCOUNT: GCP service account credentials
   - OPENAI_API_KEY: OpenAI API keys
   - AZURE_API_KEY: Azure API keys
   - STRIPE_SECRET_KEY: Stripe secret keys
   - STRIPE_PUBLISHABLE_KEY: Stripe publishable keys
   - SLACK_TOKEN: Slack API tokens
   - GITHUB_TOKEN: GitHub personal access tokens
   - TWILIO_API_KEY: Twilio API keys
   - SENDGRID_API_KEY: SendGrid API keys
   - HEROKU_API_KEY: Heroku API keys
   - API_KEY: Generic API keys
   - TOKEN: Generic tokens
   - USER_AGENT: Browser/client user agent strings
   - AWS_ARN: Amazon Resource Names
   - DATE_TIME: Date and time values
   - ORGANIZATION: Organization/company names

   **### Bundles** -- Collapsible sections using `pymdownx.details` syntax:
   Use `???+ example` (expanded) for the PII bundle and `??? example` (collapsed) for others.
   Each bundle gets a collapsible block listing its labels in a table.

   From RESEARCH.md lines 511-519:
   - `???+ example "PIILabel.PII (23 labels)"` -- PERSON_NAME through CRYPTO_ADDRESS
   - `??? example "PIILabel.PHI (1 label)"` -- PERSON_NAME
   - `??? example "PIILabel.PCI (4 labels)"` -- CREDIT_CARD, IBAN, BANK_ACCOUNT, ROUTING_NUMBER
   - `??? example "PIILabel.SECRETS (20 labels)"` -- PASSWORD through TOKEN
   - `??? example "PIILabel.TECH (2 labels)"` -- USER_AGENT, AWS_ARN
   - Mention `PIILabel.ALL` expands all bundles (45 unique labels after dedup)

5. **## Parameters** -- Table from RESEARCH.md Pattern 5 (lines 328-336):
   | Parameter | Type | Default | Description |
   labels, action (default Action.REPLACE), condition (default Condition.ANY), overrides, threshold, allowlist

6. **## Per-Label Overrides** section:
   - Explain that overrides let you apply different actions to different labels
   - Example: REPLACE emails but LOG phone numbers
   - Self-contained code example with overrides dict
   - Show expected output

7. **## Using Bundles** section:
   - Example using PIILabel.PII as shorthand for 23 labels
   - Example using PIILabel.ALL for everything
   - Self-contained code with expected output

8. **## Actions and Conditions** -- Brief scanner-specific note + link to Concepts page:
   - Most common: Action.REPLACE with Condition.ANY (redact any PII found)
   - For strict compliance: Action.BLOCK to reject input entirely
   - For monitoring: Action.LOG to detect without modifying
   - Link: "See [Concepts](../concepts.md) for detailed Action and Condition reference."

9. **## scan_input Example** -- Full self-contained example with expected output
   Different from Quick Example -- use bundles (PIILabel.PII) and show more result fields

10. **## scan_output Example** -- Full self-contained example showing output scanning
   Note: scan_output has the same signature as scan_input. Show scanning LLM response text.

IMPORTANT:
- Every code example: self-contained with ALL imports, Guard(api_key=..., tenant_id=...)
- Use EXACT enum member names from RESEARCH.md (e.g., PIILabel.EMAIL_ADDRESS not PIILabel.EMAIL)
  Wait -- check actual source: RESEARCH.md line 497 shows `PIILabel.EMAIL` and `PIILabel.PHONE`. Read the actual pii.py source to confirm the exact member names. Use whatever the source code actually defines.
- Show expected console output below every code block
- Use realistic input text with believable PII
  </action>
  <verify>
1. Run `.venv/bin/mkdocs build --strict` -- must pass.
2. Verify all 47 canonical labels appear in the labels table.
3. Verify all 5 bundles have collapsible sections.
4. Verify at least 4 code examples exist (quick, overrides, bundles, scan_input, scan_output).
5. Grep for import statements -- all must use `from meshulash_guard.scanners import PIIScanner, PIILabel`.
  </verify>
  <done>PIIScanner reference page complete with all 47 labels, 5 collapsible bundle sections, per-label overrides example, bundle usage example, and scan_input/scan_output examples. All code self-contained.</done>
</task>

<task type="auto">
  <name>Task 2: Write four TC scanner reference pages and verify full site build</name>
  <files>docs/scanners/topic.md, docs/scanners/toxicity.md, docs/scanners/cyber.md, docs/scanners/jailbreak.md</files>
  <action>
Write all four TC scanner reference pages following the same structure as PIIScanner but simpler (no bundles, no overrides).

**For EACH of the four pages**, use this consistent structure:

1. **# [Scanner Name]** -- one-line description
2. **## When to Use This** -- 1-2 paragraphs on what it protects and use cases
3. **## Quick Example** -- self-contained code with realistic input and expected output
4. **## Labels** -- table of all label enum members with "What It Detects" descriptions
5. **## Parameters** -- table (labels, action, condition, threshold, allowlist -- NO overrides for TC scanners)
6. **## Actions and Conditions** -- scanner-specific usage + link to Concepts
7. **## scan_input Example** -- full example different from Quick Example
8. **## scan_output Example** -- full example scanning LLM response

**Page-specific details:**

**docs/scanners/topic.md -- TopicScanner:**
- Description: "Classify text by topic to filter off-topic or restricted content."
- When to use: content moderation, keeping conversations on-topic, blocking discussions about restricted subjects
- Labels: ALL 30 TopicLabel members from RESEARCH.md lines 540. Use exact Python enum names (ALBUM, ANIMAL, ARTIST, ATHLETE, BUILDING, BUSINESS_FINANCE, COMPANY, COMPUTERS_INTERNET, EDUCATION_REFERENCE, EDUCATIONAL_INSTITUTION, ENTERTAINMENT_MUSIC, ETHNICITY_RACE, FAMILY_RELATIONSHIPS, FILM, HEALTH, IDENTITY_ATTACK, LEGAL_REGULATIONS, MEAN_OF_TRANSPORTATION, NATURAL_PLACE, OFFICE_HOLDER, PHILOSOPHICAL_CONCEPT, PLANT, POLITICS_GOVERNMENT, SCIENCE_MATHEMATICS, SEXUAL_EXPLICIT, SOCIETY_CULTURE, SOFTWARE_DEVELOPMENT_CODE, SPORTS, VILLAGE, WRITTEN_WORK + ALL)
- Quick example: Block SEXUAL_EXPLICIT and IDENTITY_ATTACK topics. Realistic input: "Tell me about the latest sports news" (clean) or use a blocking example
- Default action: Action.BLOCK, default condition: Condition.ANY

**docs/scanners/toxicity.md -- ToxicityScanner:**
- Description: "Detect toxic, hateful, or offensive language in text."
- When to use: content moderation, preventing hate speech, ensuring respectful interactions
- Labels: 4 ToxicityLabel members from RESEARCH.md lines 558-563: TOXICITY, HATE_SPEECH, NON_HATE, OFFENSIVE_LANGUAGE + ALL
- Quick example: Block toxic or hateful content. Realistic input with mildly offensive text.
- Default action: Action.BLOCK, default condition: Condition.ANY

**docs/scanners/cyber.md -- CyberScanner:**
- Description: "Detect cybersecurity threats, attack techniques, and malicious instructions in text."
- When to use: preventing prompt injection for cyberattack instructions, detecting malware descriptions, blocking network attack guides
- Labels: 11 CyberLabel members from RESEARCH.md lines 581-582: CLOUD_ATTACKS, CONTROL_SYSTEM_ATTACKS, CRYPTOGRAPHIC_ATTACKS, EVASION_TECHNIQUES, HARDWARE_ATTACKS, INTRUSION_TECHNIQUES, IOT_ATTACKS, MALWARE_ATTACKS, NETWORK_ATTACKS, NONE, WEB_APPLICATION_ATTACKS + ALL
- Quick example: Block malware and network attack discussions. Realistic input: "How do I perform a SQL injection attack?"
- Default action: Action.BLOCK, default condition: Condition.ANY

**docs/scanners/jailbreak.md -- JailbreakScanner:**
- Description: "Detect jailbreak attempts designed to bypass LLM safety guardrails."
- When to use: protecting LLM applications from prompt injection and jailbreak attacks
- Labels: 2 JailbreakLabel members from RESEARCH.md lines 600-603: BENIGN, JAILBREAK + ALL
- Quick example: Block jailbreak attempts. Realistic input with a DAN-style jailbreak prompt.
- Default action: Action.BLOCK, default condition: Condition.ANY
- ADD a note/admonition block (use `!!! info "Forward Compatibility"`) explaining:
  "The jailbreak detection head is currently being deployed on the server. JailbreakScanner is included in the SDK for forward compatibility -- it will activate automatically when the server-side jailbreak head becomes available. In the meantime, scan results may return empty detections."

IMPORTANT for all four pages:
- Every code example self-contained with ALL imports and Guard(api_key=..., tenant_id=...)
- Import pattern: `from meshulash_guard.scanners import TopicScanner, TopicLabel` (etc.)
- Use realistic text inputs (not lorem ipsum)
- Show expected output below every code block
- Read the actual scanner source files (referenced in context) to confirm exact enum member names before writing

**After writing all 4 pages**, run `mkdocs build --strict` to verify the complete site builds.
  </action>
  <verify>
1. Run `.venv/bin/mkdocs build --strict` -- must pass with zero errors for the COMPLETE site (all 10 pages).
2. Verify each scanner page has: title, "When to Use This", Quick Example, Labels table, Parameters table, Actions and Conditions, scan_input example, scan_output example.
3. Verify JailbreakScanner page has the forward-compatibility info admonition.
4. Count total label entries across all 4 pages: should be 30 (topic) + 4 (toxicity) + 11 (cyber) + 2 (jailbreak) = 47 labels documented.
  </verify>
  <done>All 4 TC scanner reference pages complete with label tables, working code examples, and consistent structure. JailbreakScanner has forward-compatibility note. Full site (10 pages) builds without errors.</done>
</task>

<task type="checkpoint:human-verify" gate="blocking">
  <what-built>Complete MkDocs documentation site with 10 pages: landing page with hero, quickstart, concepts, 5 scanner references (PIIScanner with bundles/overrides, TopicScanner, ToxicityScanner, CyberScanner, JailbreakScanner with forward-compat note), and deanonymize workflow.</what-built>
  <how-to-verify>
1. Start the dev server: `cd /Users/shalev/Desktop/meshulash_guard && .venv/bin/mkdocs serve`
2. Visit http://127.0.0.1:8000/
3. Check the landing page:
   - Purple branding matching AIM dashboard
   - Hero section with "Meshulash Guard" title and tagline
   - "Get Started" and "Explore Scanners" buttons
   - Code snippet below the hero
4. Click through all pages in the sidebar:
   - Quickstart: install + two scan examples with expected output
   - Concepts: Actions table, Conditions table, ScanResult fields, exceptions
   - Each scanner page: labels table, code examples, parameters
   - PIIScanner: collapsible bundle sections work (expand/collapse)
   - JailbreakScanner: forward-compatibility info box visible
   - Deanonymize: full workflow walkthrough with multi-turn example
5. Verify code blocks have copy buttons (click the copy icon)
6. Verify navigation works (sidebar links, cross-page links)
  </how-to-verify>
  <resume-signal>Type "approved" or describe any issues with layout, content, or branding</resume-signal>
</task>

</tasks>

<verification>
- `mkdocs build --strict` passes for complete site (10 pages)
- Every scanner page follows consistent structure
- PIIScanner has 47 labels + 5 collapsible bundles
- TopicScanner has 30 labels
- ToxicityScanner has 4 labels
- CyberScanner has 11 labels
- JailbreakScanner has 2 labels + forward-compat admonition
- All code examples use correct import paths from actual SDK source
- All code examples include Guard(api_key=..., tenant_id=...)
</verification>

<success_criteria>
- Every scanner has a dedicated reference page with labels, parameters, actions/conditions, and working code examples
- PIIScanner page documents all 53 label enum members (47 canonical + 5 bundles + ALL)
- All code examples are self-contained, copy-paste ready, and include expected output
- Human has verified the complete site visually and approved
</success_criteria>

<output>
After completion, create `.planning/phases/04-docs/04-03-SUMMARY.md`
</output>
