# AI Agent Guidelines

## Project Overview

Reads Slack messages from the local Chromium IndexedDB cache on disk. Slack's
desktop app (Mac App Store) persists its entire Redux state as a single
Blink-serialized blob. We decode it with `dfindexeddb` and extract messages,
channels, members, etc.

## Project Structure

```
.
├── slack_cli/                     # Python package (canonical source)
│   ├── __init__.py
│   └── __main__.py                # CLI entry point
├── pyproject.toml                 # Python packaging metadata
├── flake.nix                      # Nix dev shell + package build
├── docs/
│   └── indexeddb-format.md        # Full IndexedDB data format documentation
└── scripts/
    └── analyze_structure.py       # Generates schema data for docs
```

## Key Files

- **`slack_cli/__main__.py`** — Canonical CLI source. Entry point is `main()`, exposed as the `slack-cli` console script.
- **`pyproject.toml`** — Python packaging metadata. Declares `slack-cli` console script entry point and `dfindexeddb` dependency.
- **`docs/indexeddb-format.md`** — Documents the on-disk format: LevelDB layer, IndexedDB databases, Blink value encoding, and the full Redux state schema with field-level detail.
- **`scripts/analyze_structure.py`** — Introspects the live IndexedDB and dumps database/object-store/record-type info plus Redux state key schemas. Re-run this when the data format changes and update the docs accordingly.
- **`flake.nix`** — Nix dev shell (python3.12, uv, snappy) + standalone package build. Packages pinned PyPI deps (python-snappy==0.6.1, zstd==1.5.5.1, dfindexeddb) inline.

## Dev Environment

```bash
nix develop          # Enter shell with python3.12, uv, snappy
./slack-cli.py      # uv resolves deps automatically via inline metadata
```

Or without nix, ensure `python3.12`, `uv`, and `libsnappy` are available.

## Building

```bash
nix build            # Build standalone CLI to ./result/bin/slack-cli
nix run              # Build and run directly
nix run . -- --help  # Pass args
```

## Dependencies

All Python deps are declared inline in each script's `# /// script` metadata block. `uv` resolves and caches them automatically. The only dependency is:

- **`dfindexeddb`** — Forensic parser for Chromium IndexedDB/LevelDB and Blink V8 serialized values.

The nix flake provides **`snappy`** (the C library) because `python-snappy` needs it to compile its native extension.

## Important Rules

1. **Timeout for bash tool**: The `bash` tool MUST have a timeout specified.
2. **File writing**: Use the `write` / `edit` tools, not `cat` with heredocs.
3. **No PII in docs**: Documentation must contain **zero** identifying information — no real Slack IDs (user, channel, team, file, bot, group), names, emails, message content, or workspace names. Use anonymized placeholders like `U0XXXXXXXXX`, `C0XXXXXXXXX`, `T0XXXXXXXXX`, `"MyBot"`, etc. The analysis scripts read live data, but anything written to `docs/` must be scrubbed.

## Style

### Comment Style

A logical block of code should have a Title Case comment above it:

```python
# Build Channel Name Lookup
channel_names = {}
for cid, cdata in channels_store.items():
    ...
```