---
phase: 04-docs
plan: 02
type: execute
wave: 2
depends_on: ["04-01"]
files_modified:
  - docs/quickstart.md
  - docs/concepts.md
  - docs/deanonymize.md
autonomous: true

must_haves:
  truths:
    - "A developer with no prior knowledge can follow the quickstart to run their first scan"
    - "Action and Condition enums are explained once on Concepts page with clear descriptions"
    - "The deanonymize workflow walks through the full anonymize -> LLM -> restore pattern"
    - "Every code example is self-contained with imports and expected output"
  artifacts:
    - path: "docs/quickstart.md"
      provides: "Installation + first scan annotated walkthrough"
      min_lines: 80
    - path: "docs/concepts.md"
      provides: "Action/Condition explanation, architecture note, ScanResult structure"
      min_lines: 60
    - path: "docs/deanonymize.md"
      provides: "Full anonymize -> LLM -> restore workflow with example code"
      min_lines: 80
  key_links:
    - from: "docs/quickstart.md"
      to: "docs/concepts.md"
      via: "cross-reference link"
      pattern: "concepts"
    - from: "docs/deanonymize.md"
      to: "docs/quickstart.md"
      via: "prerequisite reference"
      pattern: "quickstart"
---

<objective>
Write the three core narrative pages: Quickstart (install + first scan), Concepts (Action/Condition/architecture), and Deanonymize workflow (anonymize -> LLM -> restore).

Purpose: These pages form the learning path for a new developer. Quickstart gets them running, Concepts explains the building blocks, and Deanonymize teaches the advanced PII workflow. Scanner reference pages (Plan 03) will link back to Concepts for Action/Condition details.
Output: Three complete documentation pages with self-contained code examples and expected outputs.
</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
</context>

<tasks>

<task type="auto">
  <name>Task 1: Write Quickstart and Concepts pages</name>
  <files>docs/quickstart.md, docs/concepts.md</files>
  <action>
**docs/quickstart.md** -- Annotated walkthrough: install + first scan. Follow the Protect AI tone (professional, approachable, practical). Structure:

1. **Installation** section:
   - `pip install meshulash-guard`
   - Note: requires Python 3.9+
   - Mention they need an API key and tenant ID from their Meshulash dashboard

2. **Your First Scan** section:
   - Full self-contained code example scanning for PII (email + phone) with Action.REPLACE
   - Use realistic input text: "Contact me at sarah@company.com or call 555-0123"
   - Show the full code with imports: Guard, Action, PIIScanner, PIILabel
   - Guard constructor: `Guard(api_key="your-api-key", tenant_id="your-tenant-id")`
   - Show expected output below the code block (result.status, result.processed_text with placeholders)
   - Brief inline annotations explaining each part: what Guard does, what PIIScanner does, what Action.REPLACE means

3. **Understanding the Result** section:
   - Brief explanation of ScanResult fields: status ("clean"/"secured"/"blocked"), processed_text, placeholders
   - Code snippet showing how to inspect result.scanners for per-scanner breakdown
   - Link to Concepts page for deeper dive on Actions/Conditions

4. **Blocking Dangerous Content** section:
   - Second example using ToxicityScanner with Action.BLOCK
   - Realistic prompt: "You're an idiot and I hate everything about your service"
   - Show expected output: status="blocked"
   - Brief explanation of BLOCK vs REPLACE behavior

5. **Next Steps** section:
   - Links to scanner reference pages, Concepts page, Deanonymize workflow

**docs/concepts.md** -- Shared concepts explained once. Structure:

1. **How It Works** section (light architecture note):
   - Use the EXACT architecture note text from RESEARCH.md (lines 723-736)
   - Explain: SDK is a client library, server does all heavy compute, scan calls involve network round-trip, deanonymize is client-side exception
   - Mention API key + tenant ID authentication

2. **Actions** section:
   - Table: Action | What Happens | Result Status
   - Action.REPLACE: redacts text with [LABEL-HASH] placeholders, status="secured"
   - Action.BLOCK: returns original text, status="blocked" (hard stop)
   - Action.LOG: returns original text, status="clean" (logged server-side)
   - Self-contained code example showing REPLACE vs BLOCK behavior

3. **Conditions** section:
   - Table: Condition | When It Triggers
   - 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)
   - Brief note: most common is Condition.ANY (the default)

4. **ScanResult** section:
   - Field-by-field reference table with types and descriptions
   - result.status, result.processed_text, result.placeholders, result.level, result.scanners, result.risk_categories
   - ScannerResult sub-fields: triggered, score, detections
   - Detection sub-fields: label, text, start, end, confidence, action

5. **Exceptions** section:
   - Table: Exception | When Raised
   - MeshulashError (base), AuthError (invalid/missing API key), ServerError (5xx, has .status_code), ConnectionError (can't reach server), ValidationError (bad request payload)
   - Code example showing try/except pattern

IMPORTANT for all code examples:
- Every snippet must be self-contained (include ALL imports and Guard initialization)
- Use realistic text inputs (not "test text" or lorem ipsum)
- Show expected output below each code block
- Import paths must match actual SDK: `from meshulash_guard import Guard, Action, Condition` and `from meshulash_guard.scanners import PIIScanner, PIILabel`
- Guard constructor MUST include both api_key and tenant_id parameters
  </action>
  <verify>
1. Run `.venv/bin/mkdocs build --strict` -- must pass with no errors.
2. Grep all code examples for correct import paths: `from meshulash_guard import` and `from meshulash_guard.scanners import`
3. Verify every code block has expected output shown below it.
  </verify>
  <done>Quickstart page walks a new developer from pip install through two working scan examples. Concepts page explains Actions, Conditions, ScanResult, exceptions, and architecture. All code examples are self-contained with imports and expected output.</done>
</task>

<task type="auto">
  <name>Task 2: Write Deanonymize workflow page</name>
  <files>docs/deanonymize.md</files>
  <action>
**docs/deanonymize.md** -- Full anonymize -> LLM -> restore workflow guide. Structure:

1. **Overview** section:
   - 1-2 paragraphs explaining the problem: you want to protect PII before sending to an LLM, but need the original values back in the response
   - The pattern: scan_input (replace PII) -> send redacted text to LLM -> scan_output (check LLM response) -> deanonymize (restore originals)
   - Key insight: deanonymize is client-side only, no server call needed

2. **The Workflow** section with numbered steps and a complete code example:
   - Use the EXACT workflow pattern from RESEARCH.md (lines 622-656) as the basis, but adapt the text to be tutorial-style
   - Step 1: Initialize Guard
   - Step 2: Scan input with PIIScanner using Action.REPLACE and PIILabel.ALL
   - Step 3: Check result -- if status is "secured", send processed_text (not original!) to LLM
   - Step 4: Show what the LLM sees and how it might respond (using placeholders)
   - Step 5: Scan LLM output with scan_output()
   - Step 6: Call guard.deanonymize() to restore originals
   - Step 7: Show final output with real values restored
   - Use realistic input: "My SSN is 123-45-6789 and my email is sarah@company.com"
   - Show expected output at each step

3. **How the Vault Works** section:
   - Placeholder format: [LABEL_NAME-HASH] (e.g., [EMAIL_ADDRESS-A1B2])
   - Vault accumulates across multiple scan_input() and scan_output() calls in the same session
   - deanonymize() uses longest-first replacement to avoid prefix overlap issues
   - deanonymize() returns text unchanged if vault is empty (safe to call always)

4. **Multi-Turn Conversations** section:
   - Example showing two consecutive scan_input() calls accumulating into the same vault
   - Show that deanonymize() can restore placeholders from any prior scan in the session
   - Explain when to call clear_cache() (new conversation/session, NOT between turns)

5. **Resetting the Session** section:
   - guard.clear_cache() -- resets the vault so no prior placeholders remain
   - When to use: starting a new conversation, user logout, explicit reset
   - When NOT to use: between turns in the same conversation (would lose earlier placeholders)

6. **Common Patterns** section:
   - Pattern: Always check result.status before deciding whether to send to LLM
   - Pattern: If status is "blocked", do NOT send to LLM -- reject the user's input
   - Pattern: If status is "clean", send original text (no PII detected)
   - Pattern: If status is "secured", send processed_text (PII replaced)

IMPORTANT:
- Every code example self-contained with imports and Guard initialization
- Guard constructor MUST include both api_key and tenant_id
- Use realistic text (SSNs, emails, names) not placeholders
- Show expected output below every code block
- Reference the Quickstart page for basic setup
  </action>
  <verify>
1. Run `.venv/bin/mkdocs build --strict` -- must pass.
2. Verify the complete workflow code example includes all 6 steps (init, scan_input, send to LLM, scan_output, deanonymize, clear_cache).
3. Grep for `guard.deanonymize` and `guard.clear_cache` to confirm both are documented.
  </verify>
  <done>Deanonymize page walks through the full anonymize -> LLM -> restore pattern with realistic code examples. Multi-turn vault behavior explained. clear_cache() usage documented with correct guidance (new session, not between turns).</done>
</task>

</tasks>

<verification>
- `mkdocs build --strict` passes with all three pages
- Quickstart has at least two complete code examples with expected output
- Concepts has Action table, Condition table, ScanResult reference, exceptions reference
- Deanonymize has end-to-end workflow example and multi-turn example
- All code examples use correct import paths matching actual SDK source
- All code examples include Guard(api_key=..., tenant_id=...) constructor
</verification>

<success_criteria>
- A developer with zero prior knowledge can follow quickstart.md to run their first scan
- Concepts page is the single source of truth for Actions, Conditions, ScanResult, and exceptions
- Deanonymize page demonstrates the complete PII protection workflow for LLM applications
- All code examples are copy-paste ready with imports and expected output
</success_criteria>

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