# Phase 4: Docs - Research

**Researched:** 2026-02-26
**Domain:** MkDocs Material documentation site for meshulash-guard Python SDK
**Confidence:** HIGH

## Summary

This research covers everything needed to plan the MkDocs Material documentation site for the meshulash-guard SDK. The SDK source code has been fully analyzed -- all scanner classes, label enums, actions, conditions, the Guard class, deanonymize workflow, and exception hierarchy are documented below. The AIM dashboard color scheme has been extracted from the production frontend (`mui_theme.ts`), and MkDocs Material's custom color, collapsible content, and code block features have been verified against official documentation.

The primary challenge is the custom landing page with a hero section. MkDocs Material supports this via template overrides (`custom_dir: overrides`) with a `home.html` template specified in `index.md` front matter. The collapsible PII bundle details use `pymdownx.details` with the `??? note` / `???+ note` syntax, which is well-supported and straightforward.

**Primary recommendation:** Use MkDocs Material 9.x with a custom color scheme matching the AIM dashboard purple (`#8b5cf6`), a hero landing page via template override, and `pymdownx.details` for collapsible PII bundle content.

## Standard Stack

### Core

| Library | Version | Purpose | Why Standard |
|---------|---------|---------|--------------|
| mkdocs | 1.6+ | Static site generator | Installed as dependency of mkdocs-material |
| mkdocs-material | 9.x | Material Design theme | Industry standard for Python SDK docs (used by LLM Guard, FastAPI, Pydantic) |

### Supporting

| Library | Version | Purpose | When to Use |
|---------|---------|---------|-------------|
| pymdown-extensions | (bundled) | Markdown extensions (details, tabbed, highlight) | Auto-installed with mkdocs-material |
| pygments | (bundled) | Syntax highlighting for code blocks | Auto-installed with mkdocs-material |

### Not Needed

| Library | Reason Not Needed |
|---------|-------------------|
| mkdocstrings | Decision: hand-written guides only, no auto-generated API reference |
| mkdocs-minify-plugin | Premature optimization for a docs site of this size |
| mkdocs-git-revision-date-localized-plugin | Nice-to-have, not required for launch |

**Installation:**
```bash
pip install mkdocs-material=="9.*"
```

## Architecture Patterns

### Recommended Project Structure

```
docs/
    index.md                    # Landing page (uses home.html template)
    quickstart.md               # Installation + first scan walkthrough
    concepts.md                 # Action/Condition explained once
    scanners/
        pii.md                  # PIIScanner reference
        topic.md                # TopicScanner reference
        toxicity.md             # ToxicityScanner reference
        cyber.md                # CyberScanner reference
        jailbreak.md            # JailbreakScanner reference
    deanonymize.md              # Full anonymize -> LLM -> restore workflow
    stylesheets/
        extra.css               # Custom colors matching AIM dashboard
    images/
        logo.svg                # Meshulash logo (from AIM/front/public/)
overrides/
    home.html                   # Custom landing page template with hero
mkdocs.yml                     # Site configuration
```

### Pattern 1: mkdocs.yml Complete Configuration

**What:** The full MkDocs Material configuration for this project.
**Confidence:** HIGH -- verified against official MkDocs Material 9.x docs.

```yaml
# mkdocs.yml
site_name: Meshulash Guard
site_url: https://docs.meshulash.ai  # Update to actual domain
site_description: Python SDK for AI security - protect LLM applications from PII leakage, toxic content, and cyber threats

theme:
  name: material
  custom_dir: overrides
  palette:
    scheme: meshulash
  font:
    text: Roboto
    code: Roboto Mono
  logo: images/logo.svg
  favicon: images/logo.svg
  features:
    - navigation.instant
    - navigation.instant.prefetch
    - navigation.tracking
    - navigation.top
    - navigation.footer
    - content.code.copy
    - content.code.annotate
    - content.tabs.link

markdown_extensions:
  # Python Markdown
  - tables
  - admonition
  - attr_list
  - md_in_html

  # PyMdown Extensions
  - pymdownx.details
  - pymdownx.superfences
  - pymdownx.highlight:
      anchor_linenums: true
      line_spans: __span
      pygments_lang_class: true
  - pymdownx.inlinehilite
  - pymdownx.tabbed:
      alternate_style: true
  - pymdownx.snippets

extra_css:
  - stylesheets/extra.css

extra:
  social:
    - icon: fontawesome/brands/github
      link: https://github.com/meshulash/meshulash-guard

copyright: Copyright &copy; 2026 Meshulash

nav:
  - Home: index.md
  - Quickstart: quickstart.md
  - Concepts: concepts.md
  - Scanners:
    - PIIScanner: scanners/pii.md
    - TopicScanner: scanners/topic.md
    - ToxicityScanner: scanners/toxicity.md
    - CyberScanner: scanners/cyber.md
    - JailbreakScanner: scanners/jailbreak.md
  - Deanonymize: deanonymize.md
```

### Pattern 2: Custom Color Scheme (AIM Dashboard Colors)

**What:** CSS custom properties to match the AIM dashboard theme.
**Source:** Extracted from `/Users/shalev/Desktop/AIM/front/src/mui_theme.ts`
**Confidence:** HIGH -- colors read directly from production AIM frontend code.

AIM Dashboard palette (from `mui_theme.ts`):
- **Primary:** `#8b5cf6` (purple/violet)
- **Secondary:** `#555`
- **Success:** `#22c55e`
- **Warning:** `#f59e0b`
- **Error:** `#e53935`
- **Background:** `#ffffff` (white, clean)
- **Text:** `#1f1f1f` (near-black)
- **Subtle text:** `#6b7280`
- **Border:** `#e5e7eb`
- **Font family:** -apple-system, BlinkMacSystemFont, 'Segoe UI', 'Roboto', sans-serif
- **Border radius:** 8px

```css
/* docs/stylesheets/extra.css */

/* Custom color scheme matching AIM dashboard */
[data-md-color-scheme="meshulash"] {
  /* Primary: AIM dashboard purple */
  --md-primary-fg-color:        #8b5cf6;
  --md-primary-fg-color--light: #a78bfa;
  --md-primary-fg-color--dark:  #7c3aed;

  /* Accent: same purple family */
  --md-accent-fg-color:         #8b5cf6;

  /* Default scheme (light background) */
  --md-default-bg-color:        #ffffff;
  --md-default-fg-color:        #1f1f1f;
}
```

### Pattern 3: Custom Landing Page (Hero Section)

**What:** Template override for a hero-style landing page.
**Confidence:** MEDIUM -- approach verified in MkDocs Material docs and community discussions, but exact HTML/CSS will need iteration.

In `docs/index.md`:
```yaml
---
template: home.html
hide:
  - navigation
  - toc
---
```

In `overrides/home.html`:
```html
{% extends "main.html" %}

{% block tabs %}
  {{ super() }}

  <style>
    /* Hero section styling */
    .md-main {
      flex-grow: 0;
    }
    .mdx-hero {
      margin: 0 .8rem;
      color: var(--md-default-fg-color);
    }
    .mdx-hero .md-button {
      margin-top: .5rem;
      margin-right: .5rem;
    }
    .mdx-hero__content {
      padding-bottom: 6rem;
      padding-top: 6rem;
      text-align: center;
    }
    .mdx-hero__content h1 {
      font-weight: 700;
      margin-bottom: 1rem;
      color: var(--md-primary-fg-color);
    }
  </style>

  <section class="mdx-hero" data-md-color-scheme="meshulash">
    <div class="mdx-hero__content md-grid">
      <h1>Meshulash Guard</h1>
      <p>Protect your LLM applications from PII leakage, toxic content, and cyber threats with a few lines of Python.</p>
      <a href="quickstart/" class="md-button md-button--primary">Get Started</a>
      <a href="scanners/pii/" class="md-button">Explore Scanners</a>
    </div>
  </section>

  <!-- Quickstart code snippet -->
  <section class="md-grid" style="padding-bottom: 4rem;">
    {{ page.content }}
  </section>
{% endblock %}
```

### Pattern 4: Collapsible PII Bundles

**What:** Expandable details blocks for PII bundle label listings.
**Source:** Official MkDocs Material admonitions documentation.
**Confidence:** HIGH -- `pymdownx.details` is a core supported extension.

```markdown
???+ example "PII Bundle (23 labels)"
    Expands all identity, contact, and financial labels:

    | Label | What It Detects |
    |-------|-----------------|
    | `PERSON_NAME` | Full names of individuals |
    | `EMAIL_ADDRESS` | Email addresses (RFC 5321/5322 validated) |
    | ... | ... |

??? example "SECRETS Bundle (20 labels)"
    All credential and secret token labels:

    | Label | What It Detects |
    |-------|-----------------|
    | `PASSWORD` | Password strings (entropy-validated) |
    | `AWS_ACCESS_KEY` | AWS access key IDs |
    | ... | ... |
```

The `???+` syntax makes the block expanded by default (use for the most common bundle like PII). The `???` syntax keeps it collapsed (use for secondary bundles).

### Pattern 5: Scanner Reference Page Structure

**What:** Consistent page structure for each scanner reference, inspired by Protect AI / LLM Guard docs style.
**Confidence:** HIGH -- structure derived from LLM Guard analysis + CONTEXT.md decisions.

Each scanner page should follow this structure:

```markdown
# PIIScanner

Brief 1-line description of what this scanner does.

## When to Use This

1-2 paragraphs: what it protects against, real-world use cases.

## Quick Example

```python
from meshulash_guard import Guard, Action, Condition
from meshulash_guard.scanners import PIIScanner, PIILabel

guard = Guard(api_key="sk-xxx", tenant_id="your-tenant-id")

pii = PIIScanner(
    labels=[PIILabel.EMAIL, PIILabel.PHONE],
    action=Action.REPLACE,
    condition=Condition.ANY,
)

result = guard.scan_input("My email is john@example.com", scanners=[pii])
print(result.status)          # "secured"
print(result.processed_text)  # "My email is [EMAIL_ADDRESS-A1B2]"
```

Expected output:
```
secured
My email is [EMAIL_ADDRESS-A1B2]
```

## Labels

### Individual Labels
| Label | What It Detects |
|-------|-----------------|
| `PIILabel.EMAIL_ADDRESS` | Email addresses |
| ... | ... |

### Bundles
???+ example "PIILabel.PII (23 labels)"
    | Label | What It Detects |
    |-------|-----------------|
    | ... | ... |

## Parameters

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `labels` | `list[PIILabel]` | required | Labels to detect |
| `action` | `Action` | `Action.REPLACE` | Action when detected |
| `condition` | `Condition` | `Condition.ANY` | Gating condition |
| `overrides` | `dict[PIILabel, Action]` | `None` | Per-label action overrides |
| `threshold` | `float` | `None` | Confidence threshold (0.0-1.0) |
| `allowlist` | `list[str]` | `None` | Values to allow through |

## Actions and Conditions

Brief scanner-specific usage, linking to Concepts page.

## scan_input Example
(Full self-contained example with expected output)

## scan_output Example
(Full self-contained example with expected output)
```

### Anti-Patterns to Avoid

- **Auto-generated API reference without narrative:** Decision says hand-written guides only. Do not use mkdocstrings.
- **Examples without imports:** Every code snippet must be self-contained and copy-paste ready per CONTEXT.md decision.
- **Nested sidebar navigation:** Decision says flat list of scanners, no nesting.
- **Separate engine reference page:** Decision says label tables go on each scanner page, not a separate page.

## Don't Hand-Roll

| Problem | Don't Build | Use Instead | Why |
|---------|-------------|-------------|-----|
| Syntax highlighting | Custom JS highlighter | `pymdownx.highlight` + Pygments | Pygments supports Python natively with zero config |
| Collapsible sections | Custom JS accordion | `pymdownx.details` (`???` syntax) | Native MkDocs Material support, accessible, no JS needed |
| Copy button on code blocks | Custom clipboard JS | `content.code.copy` theme feature | Single line in mkdocs.yml, works everywhere |
| Dark/light mode | Custom CSS toggle | MkDocs Material palette toggle | Built-in, handles all component colors automatically |
| Custom landing page | Full custom static site | Template override with `custom_dir` | Keeps MkDocs build pipeline, just overrides one template |
| Responsive layout | Custom media queries | MkDocs Material responsive grid | Already responsive out of the box |

**Key insight:** MkDocs Material 9.x is extremely feature-rich. Almost every "custom" need has a built-in solution via theme features or markdown extensions. Do not write custom JavaScript or CSS for functionality that MkDocs Material already provides.

## Common Pitfalls

### Pitfall 1: CNAME File Deleted on Deploy

**What goes wrong:** `mkdocs gh-deploy --force` overwrites the `gh-pages` branch, deleting the GitHub Pages CNAME file that maps the custom domain.
**Why it happens:** The CNAME file is on the `gh-pages` branch but not in the build output.
**How to avoid:** Place a `CNAME` file in the `docs/` directory containing the bare domain (e.g., `docs.meshulash.ai`). MkDocs will copy it to the build output automatically.
**Warning signs:** Custom domain stops working after a deploy.

### Pitfall 2: Code Examples That Don't Match Actual API

**What goes wrong:** Docs show an API that doesn't match the actual SDK.
**Why it happens:** Copy-paste from design docs instead of actual source code.
**How to avoid:** Every code example must use the exact imports, class names, and parameter names from the actual SDK source. Reference material below in the "SDK API Reference (Source of Truth)" section.
**Warning signs:** Import paths or parameter names that don't exist in the actual code.

### Pitfall 3: Missing `pymdownx.details` Extension

**What goes wrong:** Collapsible `???` blocks render as literal text instead of expandable sections.
**Why it happens:** `pymdownx.details` not listed in `markdown_extensions` in `mkdocs.yml`.
**How to avoid:** Always include all three: `admonition`, `pymdownx.details`, `pymdownx.superfences`.
**Warning signs:** Raw `???` text visible on the rendered page.

### Pitfall 4: Indentation in Details/Admonition Blocks

**What goes wrong:** Content inside `???` or `!!!` blocks doesn't render correctly.
**Why it happens:** MkDocs Material requires exactly 4 spaces of indentation for content inside admonition/details blocks.
**How to avoid:** Use 4-space indentation consistently. Tables and code blocks inside details blocks need the same indentation.
**Warning signs:** Broken tables or unformatted text inside collapsible blocks.

### Pitfall 5: Custom Template Not Found

**What goes wrong:** `template: home.html` in front matter causes a build error.
**Why it happens:** The template file is not in the `custom_dir` directory, or `custom_dir` is not set in `mkdocs.yml`.
**How to avoid:** Ensure `theme.custom_dir: overrides` is set and `overrides/home.html` exists.
**Warning signs:** Build error mentioning template not found.

### Pitfall 6: Label Values Are Case-Sensitive with Spaces

**What goes wrong:** Documentation shows incorrect label values (e.g., `BUSINESS_FINANCE` instead of `"Business & Finance"`).
**Why it happens:** Confusing Python enum member names with their `.value` strings.
**How to avoid:** In documentation, always show the Python enum member name (e.g., `TopicLabel.BUSINESS_FINANCE`). In label reference tables showing "what it detects", the user never needs the raw string value -- they use the enum.
**Warning signs:** Users trying to pass raw strings instead of enum members.

## Code Examples

### SDK API Reference (Source of Truth)

This section documents the actual SDK API as implemented in the source code. All documentation code examples MUST use these exact signatures.

#### Guard Class

```python
# Source: /Users/shalev/Desktop/meshulash_guard/src/meshulash_guard/guard.py
from meshulash_guard import Guard

guard = Guard(
    api_key="sk-xxx",              # Required: X-Api-Key header
    tenant_id="meshulash-3lqgn",   # Required: X-Tenant-Id header
    server_url="https://...",      # Optional: defaults to https://app.meshulash.ai
    timeout=60,                    # Optional: request timeout in seconds
)

# Scan input text (e.g., user prompt before sending to LLM)
result = guard.scan_input(text="...", scanners=[...])

# Scan output text (e.g., LLM response before returning to user)
result = guard.scan_output(text="...", scanners=[...])

# Restore original values from placeholders (client-side, no server call)
restored = guard.deanonymize(text="...")

# Reset the placeholder session
guard.clear_cache()
```

#### ScanResult Object

```python
# Source: /Users/shalev/Desktop/meshulash_guard/src/meshulash_guard/models.py
result.status            # str: "clean" | "secured" | "blocked"
result.processed_text    # str: text after actions applied (may contain placeholders)
result.placeholders      # dict[str, str]: {"[EMAIL_ADDRESS-A1B2]": "john@example.com"}
result.level             # int: severity 0-5
result.scanners          # dict[str, ScannerResult]: per-scanner breakdown
result.risk_categories   # list[str]: e.g. ["PII", "SECRETS"]

# ScannerResult (per-scanner)
sr = result.scanners["sdk_piiscanner_0"]
sr.triggered   # bool
sr.score       # float
sr.detections  # list[Detection]

# Detection
d = sr.detections[0]
d.label        # str: e.g. "EMAIL_ADDRESS"
d.text         # str: the detected text
d.start        # int: start character offset
d.end          # int: end character offset
d.confidence   # float: detection confidence
d.action       # Action: action applied
```

#### Action and Condition Enums

```python
# Source: /Users/shalev/Desktop/meshulash_guard/src/meshulash_guard/enums.py
from meshulash_guard import Action, Condition

# Actions
Action.REPLACE  # Redact detected text with [LABEL-HASH] placeholders, status = "secured"
Action.BLOCK    # Return original text unmodified, status = "blocked"
Action.LOG      # Return original text unmodified, status = "clean" (logged server-side)

# Conditions
Condition.ANY         # At least one detection triggers
Condition.ALL         # All required labels must be detected
Condition.K_OF        # K or more total hits
Condition.CONTEXTUAL  # TC must trigger AND (NER or regex must trigger)
```

#### PIIScanner

```python
# Source: /Users/shalev/Desktop/meshulash_guard/src/meshulash_guard/scanners/pii.py
from meshulash_guard.scanners import PIIScanner, PIILabel
from meshulash_guard import Action, Condition

pii = PIIScanner(
    labels=[PIILabel.EMAIL, PIILabel.PHONE],  # Required: one or more PIILabel members
    action=Action.REPLACE,                     # Default: Action.REPLACE
    condition=Condition.ANY,                   # Default: Condition.ANY
    overrides={PIILabel.PHONE: Action.LOG},    # Optional: per-label action overrides
    threshold=0.8,                             # Optional: confidence threshold
    allowlist=["test@example.com"],            # Optional: values to allow through
)
```

PIILabel has 53 members:
- **47 canonical labels:** PERSON_NAME, NATIONAL_ID, DRIVER_LICENSE, USERNAME, TAX_NUMBER, ACCOUNT_ID, BUSINESS_ID, EMAIL_ADDRESS, PHONE_NUMBER, STREET_ADDRESS, CITY, COUNTY, STATE, COUNTRY, POSTAL_CODE, IP_ADDRESS, MAC_ADDRESS, URL, CREDIT_CARD, IBAN, BANK_ACCOUNT, ROUTING_NUMBER, CRYPTO_ADDRESS, PASSWORD, SECRET_KEY, ACCESS_TOKEN, PRIVATE_KEY, CONNECTION_STRING, AWS_ACCESS_KEY, AWS_SECRET_KEY, GCP_API_KEY, GCP_SERVICE_ACCOUNT, OPENAI_API_KEY, AZURE_API_KEY, STRIPE_SECRET_KEY, STRIPE_PUBLISHABLE_KEY, SLACK_TOKEN, GITHUB_TOKEN, TWILIO_API_KEY, SENDGRID_API_KEY, HEROKU_API_KEY, API_KEY, TOKEN, USER_AGENT, AWS_ARN, DATE_TIME, ORGANIZATION
- **5 bundle shortcuts:** PII (23 labels), PHI (1 label), PCI (4 labels), SECRETS (20 labels), TECH (2 labels)
- **1 wildcard:** ALL (expands all bundles, 45 unique labels after dedup)

PII Bundle (23 labels): PERSON_NAME, NATIONAL_ID, DRIVER_LICENSE, USERNAME, TAX_NUMBER, ACCOUNT_ID, BUSINESS_ID, EMAIL_ADDRESS, PHONE_NUMBER, STREET_ADDRESS, CITY, COUNTY, STATE, COUNTRY, POSTAL_CODE, IP_ADDRESS, MAC_ADDRESS, URL, CREDIT_CARD, IBAN, BANK_ACCOUNT, ROUTING_NUMBER, CRYPTO_ADDRESS

PHI Bundle (1 label): PERSON_NAME

PCI Bundle (4 labels): CREDIT_CARD, IBAN, BANK_ACCOUNT, ROUTING_NUMBER

SECRETS Bundle (20 labels): PASSWORD, SECRET_KEY, ACCESS_TOKEN, PRIVATE_KEY, CONNECTION_STRING, AWS_ACCESS_KEY, AWS_SECRET_KEY, GCP_API_KEY, GCP_SERVICE_ACCOUNT, OPENAI_API_KEY, AZURE_API_KEY, STRIPE_SECRET_KEY, STRIPE_PUBLISHABLE_KEY, SLACK_TOKEN, GITHUB_TOKEN, TWILIO_API_KEY, SENDGRID_API_KEY, HEROKU_API_KEY, API_KEY, TOKEN

TECH Bundle (2 labels): USER_AGENT, AWS_ARN

#### TopicScanner

```python
# Source: /Users/shalev/Desktop/meshulash_guard/src/meshulash_guard/scanners/topic.py
from meshulash_guard.scanners import TopicScanner, TopicLabel
from meshulash_guard import Action, Condition

topic = TopicScanner(
    labels=[TopicLabel.SEXUAL_EXPLICIT, TopicLabel.IDENTITY_ATTACK],
    action=Action.BLOCK,        # Default: Action.BLOCK
    condition=Condition.ANY,    # Default: Condition.ANY
    threshold=0.7,              # Optional
    allowlist=[],               # Optional
)
```

TopicLabel members (29 + ALL):
Album, Animal, Artist, Athlete, Building, Business & Finance, Company, Computers & Internet, Education & Reference, EducationalInstitution, Entertainment & Music, Ethnicity & Race, Family & Relationships, Film, Health, Identity_Attack, Legal & Regulations, MeanOfTransportation, NaturalPlace, OfficeHolder, Philosophical Concept, Plant, Politics & Government, Science & Mathematics, Sexual_Explicit, Society & Culture, Software Development & Code, Sports, Village, WrittenWork

Python enum member 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

#### ToxicityScanner

```python
# Source: /Users/shalev/Desktop/meshulash_guard/src/meshulash_guard/scanners/toxicity.py
from meshulash_guard.scanners import ToxicityScanner, ToxicityLabel
from meshulash_guard import Action, Condition

toxicity = ToxicityScanner(
    labels=[ToxicityLabel.TOXICITY, ToxicityLabel.HATE_SPEECH],
    action=Action.BLOCK,        # Default: Action.BLOCK
    condition=Condition.ANY,    # Default: Condition.ANY
    threshold=0.7,              # Optional
    allowlist=[],               # Optional
)
```

ToxicityLabel members (4 + ALL):
- TOXICITY (value: "Toxicity")
- HATE_SPEECH (value: "hate speech")
- NON_HATE (value: "non-hate")
- OFFENSIVE_LANGUAGE (value: "offensive language")
- ALL

#### CyberScanner

```python
# Source: /Users/shalev/Desktop/meshulash_guard/src/meshulash_guard/scanners/cyber.py
from meshulash_guard.scanners import CyberScanner, CyberLabel
from meshulash_guard import Action, Condition

cyber = CyberScanner(
    labels=[CyberLabel.MALWARE_ATTACKS, CyberLabel.NETWORK_ATTACKS],
    action=Action.BLOCK,        # Default: Action.BLOCK
    condition=Condition.ANY,    # Default: Condition.ANY
    threshold=0.7,              # Optional
    allowlist=[],               # Optional
)
```

CyberLabel members (11 + ALL):
- CLOUD_ATTACKS, CONTROL_SYSTEM_ATTACKS, CRYPTOGRAPHIC_ATTACKS, EVASION_TECHNIQUES, HARDWARE_ATTACKS, INTRUSION_TECHNIQUES, IOT_ATTACKS, MALWARE_ATTACKS, NETWORK_ATTACKS, NONE, WEB_APPLICATION_ATTACKS, ALL

#### JailbreakScanner

```python
# Source: /Users/shalev/Desktop/meshulash_guard/src/meshulash_guard/scanners/jailbreak.py
from meshulash_guard.scanners import JailbreakScanner, JailbreakLabel
from meshulash_guard import Action, Condition

jailbreak = JailbreakScanner(
    labels=[JailbreakLabel.JAILBREAK],
    action=Action.BLOCK,        # Default: Action.BLOCK
    condition=Condition.ANY,    # Default: Condition.ANY
    threshold=0.7,              # Optional
    allowlist=[],               # Optional
)
```

JailbreakLabel members (2 + ALL):
- BENIGN (value: "benign")
- JAILBREAK (value: "jailbreak")
- ALL

**NOTE:** The jailbreak TC head is coming soon on the server. Results may be empty until deployed. The docs should note this.

#### Exception Hierarchy

```python
# Source: /Users/shalev/Desktop/meshulash_guard/src/meshulash_guard/exceptions.py
from meshulash_guard import MeshulashError, AuthError, ServerError, ConnectionError, ValidationError

# Hierarchy:
# MeshulashError (base)
#   AuthError          - API key invalid or missing
#   ServerError        - Server returned 5xx (has .status_code attribute)
#   ConnectionError    - Could not reach server
#   ValidationError    - Request payload failed server-side validation
```

#### Deanonymize Workflow (Complete Pattern)

```python
# Source: guard.py scan_input + deanonymize + clear_cache
from meshulash_guard import Guard, Action
from meshulash_guard.scanners import PIIScanner, PIILabel

# 1. Initialize
guard = Guard(api_key="sk-xxx", tenant_id="meshulash-3lqgn")

# 2. Scan input (PII gets replaced with placeholders)
pii = PIIScanner(labels=[PIILabel.ALL], action=Action.REPLACE)
result = guard.scan_input(
    text="My SSN is 123-45-6789 and email is john@example.com",
    scanners=[pii],
)

print(result.status)          # "secured"
print(result.processed_text)  # "My SSN is [NATIONAL_ID-X1Y2] and email is [EMAIL_ADDRESS-A1B2]"
print(result.placeholders)    # {"[NATIONAL_ID-X1Y2]": "123-45-6789", "[EMAIL_ADDRESS-A1B2]": "john@example.com"}

# 3. Send REDACTED text to LLM (not the original!)
llm_response = call_your_llm(result.processed_text)
# LLM sees: "My SSN is [NATIONAL_ID-X1Y2] and email is [EMAIL_ADDRESS-A1B2]"
# LLM responds: "I see you provided [NATIONAL_ID-X1Y2] and [EMAIL_ADDRESS-A1B2]."

# 4. Scan LLM output
output_result = guard.scan_output(text=llm_response, scanners=[pii])

# 5. Restore originals (client-side, no server call)
final = guard.deanonymize(output_result.processed_text)
print(final)  # "I see you provided 123-45-6789 and john@example.com."

# 6. (Optional) Reset for new conversation
guard.clear_cache()
```

Key implementation details for docs:
- `deanonymize()` uses longest-first sort for defensive placeholder replacement
- Vault accumulates across multiple `scan_input()` / `scan_output()` calls
- `deanonymize()` is a no-op if vault is empty (returns text unchanged)
- No server round-trip -- purely client-side string replacement

## AIM Dashboard Theme Reference

Extracted from `/Users/shalev/Desktop/AIM/front/src/mui_theme.ts` and `/Users/shalev/Desktop/AIM/front/src/styles/App.css`:

| Property | Value | Usage |
|----------|-------|-------|
| Primary color | `#8b5cf6` | Main brand purple -- header, links, buttons |
| Primary light | `#a78bfa` | Hover states, lighter accents |
| Primary dark | `#7c3aed` | Active states, emphasis |
| Secondary | `#555` | Secondary text, icons |
| Success | `#22c55e` | Success states |
| Warning | `#f59e0b` | Warning states |
| Error | `#e53935` | Error states, destructive actions |
| Background | `#ffffff` | Page background |
| Text primary | `#1f1f1f` | Body text |
| Text secondary | `#6b7280` | Subtitles, secondary text |
| Border | `#e5e7eb` | Dividers, card borders |
| Hover bg | `#f3f4f6` | Hover backgrounds |
| Active bg | `#e5e7eb` | Selected/active item background |
| Border radius | `8px` | Consistent rounded corners |
| Logo font | "Alef", bold | Sidebar brand text |
| Body font | system stack (SF, Roboto) | Content text |
| Primary shadow | `0 1px 8px rgba(139, 92, 246, 0.3)` | Button hover shadows |

Logo assets available at:
- `/Users/shalev/Desktop/AIM/front/public/Meshulash.svg` (dark logo on light bg)
- `/Users/shalev/Desktop/AIM/front/public/Meshulash_white.svg` (white logo on dark bg)
- `/Users/shalev/Desktop/AIM/front/public/images/Meshulash BOLD RIGHT 15.svg` (sidebar logo with text)

## Protect AI / LLM Guard Docs Tone Reference

Based on analysis of the LLM Guard documentation at protectai.github.io/llm-guard/:

**Tone characteristics:**
- Professional but approachable -- technical without unnecessary jargon
- Practical focus -- every section drives toward actionable implementation
- Progressive complexity -- concepts first, then code, then advanced options
- Direct and encouraging -- "Begin your journey", "Let's get started"
- Evidence-based -- includes supported entity lists, benchmarks where relevant

**Page structure pattern (per scanner):**
1. Introduction (1-2 sentences)
2. Conceptual foundation (what this protects against)
3. Technical details (labels, entities, configurations)
4. Code examples with usage
5. Parameters table
6. Cross-links to related tools

**Navigation pattern:**
- Flat sidebar with scanner names directly listed
- Input Scanners and Output Scanners as main sections
- Each scanner is a separate page
- Tutorials section for integration patterns

## Architecture Note Content

The CONTEXT.md specifies a "light architecture note" explaining the SDK talks to a security server. Here is the recommended content for the Concepts page:

```
The meshulash-guard SDK is a client library that sends your text to a
Meshulash security server for analysis. The server runs NER models,
regex patterns, text classifiers, and validators -- all the heavy
computation happens server-side. The SDK translates your scanner
configuration into a format the server understands, sends it over
HTTPS, and returns structured results.

This means:
- You need a running security server (cloud or on-prem)
- Scan calls involve a network round-trip (plan for ~100-500ms latency)
- An API key and tenant ID authenticate your requests
- The deanonymize step is the one exception -- it runs entirely
  client-side with no server call
```

## Custom Domain Deployment

**Confidence:** MEDIUM -- approach well-documented but exact DNS depends on hosting provider.

For GitHub Pages with custom domain:
1. Place a `CNAME` file in `docs/` containing the bare domain: `docs.meshulash.ai`
2. Set `site_url: https://docs.meshulash.ai` in `mkdocs.yml`
3. Deploy with `mkdocs gh-deploy --force` or GitHub Actions
4. Configure DNS: CNAME record pointing `docs.meshulash.ai` to `<org>.github.io`

GitHub Actions workflow (`.github/workflows/docs.yml`):
```yaml
name: Deploy docs
on:
  push:
    branches: [main]
permissions:
  contents: write
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: 3.x
      - run: pip install mkdocs-material=="9.*"
      - run: mkdocs gh-deploy --force
```

## Open Questions

1. **Exact custom domain:** The docs reference `docs.meshulash.ai` but the actual domain needs to be confirmed by the user. The planner should use a placeholder that's easy to update.

2. **Logo format for MkDocs:** The Meshulash SVG logo exists in the AIM repo but may need adjustment (sizing, color) for the MkDocs header. The planner should include a task to copy and potentially adapt the logo.

3. **Dark mode support:** The CONTEXT.md doesn't mention dark mode. The AIM dashboard is light-only. Recommendation: ship light mode only in v1, matching the AIM dashboard. MkDocs Material supports adding dark mode later via palette toggle.

4. **GitHub Actions vs manual deploy:** The CONTEXT.md doesn't specify deployment method. The planner should include the GitHub Actions workflow as the standard approach but note that `mkdocs gh-deploy --force` works for manual deploys.

## Sources

### Primary (HIGH confidence)
- `/Users/shalev/Desktop/meshulash_guard/src/meshulash_guard/` -- all SDK source files (guard.py, models.py, enums.py, exceptions.py, scanners/*.py)
- `/Users/shalev/Desktop/AIM/front/src/mui_theme.ts` -- AIM dashboard color palette
- `/Users/shalev/Desktop/AIM/front/src/styles/App.css` -- AIM dashboard global styles
- `/Users/shalev/Desktop/AIM/front/public/` -- Logo SVG assets
- MkDocs Material official docs: getting-started, changing-the-colors, admonitions, setting-up-navigation, code-blocks, content-tabs, data-tables, customization, publishing-your-site, setting-up-the-footer, setting-up-the-header, changing-the-fonts

### Secondary (MEDIUM confidence)
- Protect AI / LLM Guard docs (protectai.github.io/llm-guard/) -- tone and structure reference
- MkDocs Material GitHub Discussions #7390 -- custom landing page approach

### Tertiary (LOW confidence)
- Custom domain DNS configuration -- depends on actual hosting setup

## Metadata

**Confidence breakdown:**
- Standard stack: HIGH -- MkDocs Material 9.x verified via official docs
- Architecture/structure: HIGH -- derived from CONTEXT.md decisions + SDK source analysis
- AIM colors: HIGH -- extracted directly from production AIM frontend code
- Landing page approach: MEDIUM -- verified concept via official docs and community, exact HTML/CSS needs iteration
- Pitfalls: HIGH -- documented from official docs and common community issues
- Deployment: MEDIUM -- standard approach verified, domain-specific config depends on user

**Research date:** 2026-02-26
**Valid until:** 2026-03-26 (MkDocs Material is stable, unlikely to change significantly)
