initial commit

AGENTS.md

@@ -0,0 +1,75 @@
+# 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():
+    ...
+```