# Usage Guide

This guide explains how to use Cleanprompt effectively and safely.

## Project Links

- Website: [https://nitty-witty.com/cleanprompt](https://nitty-witty.com/cleanprompt)
- GitHub: [https://github.com/kedarvj/cleanprompt](https://github.com/kedarvj/cleanprompt)

## Basic workflow

1. Paste raw text (logs/configs/queries/output) into **Input**.
2. Select a **Context Preset**.
3. (Optional) Configure **Advanced Filtering**.
4. (Optional) Add **Manual Find/Replace Rules**.
5. Click **Obfuscate**.
6. Review **Obfuscated Output**, **Diff View**, and **Detected Changes**.
7. Copy output or export mapping JSON.

## Context presets

- `Generic`: broad detection across all supported categories.
- `MySQL Logs`: tuned for DB/log snippets and common secret formats.
- `AWS Config`: tuned for cloud keys/secrets and infrastructure identifiers.
- `Network Output`: tuned for IP/hostname/MAC and related identifiers.

Tip: start with `Generic`, then narrow if you see false positives.

## Advanced filtering

Use **Show Advanced Filtering** to toggle specific pattern detectors.

- **Choose All** enables all detectors.
- **Choose None** disables all detectors (useful for manual-only mode).

Use case: disable categories that are too noisy for your specific input type.

## Manual find/replace rules

Use **Show Manual Find/Replace** for organization-specific values that regex patterns do not catch.

Each rule supports:

- `Find`: plain text or regex pattern.
- `Replace with`: replacement value.
- `Regex`: toggle to interpret `Find` as regex.
- `Flags`: regex flags (default `g`).

Rules run after auto-detection, so they can refine final output.

## Deterministic mapping and reset

Within a session, identical raw values map to the same placeholder token.

Example:

- `db-prod.internal` -> `HOST_1`
- Next occurrence of `db-prod.internal` -> `HOST_1` again

Use **Reset Session Mapping** to clear token history and restart counters.

## Mapping JSON export

`Download Mapping JSON` includes:

- `mapping`: raw value to token
- `reverseMapping`: token to raw value
- `generatedAt`: ISO timestamp
- `presetKey`: active preset

Use export only in trusted workflows because it can enable de-obfuscation.

## Reading results

- **Detected Changes**: human-readable list of each replacement.
- **Diff View**: side-by-side original vs obfuscated text for quick review.
- **Stats**: aggregate counts by category (global via API when available, local fallback otherwise).

## Best practices

- Always manually review obfuscated output before sharing externally.
- Prefer narrower presets for domain-specific text.
- Add manual rules for internal names, account aliases, or proprietary tags.
- Do not share mapping files in public channels.

## Known limitations

- Regex detection is heuristic and may miss edge cases.
- Some values may be over-masked or under-masked.
- Very large inputs can reduce diff rendering performance.
- Shared stats require serving over `http://` with PHP API access.