discord-tools-cli 0.1.0__tar.gz

discord_tools_cli-0.1.0/.github/workflows/tests.yml

@@ -0,0 +1,53 @@
+name: Tests
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+
+jobs:
+  test:
+    name: Python ${{ matrix.python-version }}
+    runs-on: macos-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version:
+          - "3.11"
+          - "3.12"
+          - "3.13"
+          - "3.14"
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+
+      - name: Install package
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install -e ".[dev]"
+
+      - name: Run tests
+        run: python -m pytest
+
+      - name: Compile sources
+        run: python -m compileall -q src
+
+      - name: Check CLI help
+        run: |
+          discord-tools --help
+          discord-tools auth --help
+          discord-tools doctor --help
+          discord-tools discover --help
+          discord-tools search --help
+          discord-tools send --help
+          discord-tools create --help
+          discord-tools clear-messages --help
+          discord-tools bot --help

discord_tools_cli-0.1.0/.gitignore

@@ -0,0 +1,18 @@
+.DS_Store
+.venv/
+__pycache__/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+*.egg-info/
+dist/
+build/
+
+# .env.example stays untracked too: the global secrets hook blocks *.env* files
+# outright. The same content lives in README setup docs instead.
+.env
+.env.*
+
+.discord-tools/
+exports/
+*.log

discord_tools_cli-0.1.0/AGENTS.md

@@ -0,0 +1,65 @@
+# discord-tools — agent brief
+
+Public repo — contributor-facing. telegram-tools for Discord: a local CLI on
+Discord's **bot system** — no self-bots, ever (ToS).
+Bot token per profile in `~/.discord-tools/` (0600, env override); a bot per
+agent is the intended use, `--profile <name>` picks one.
+
+`SPEC.md` is the build contract — read it before touching code. Shaping record:
+`~/code/incubator/discord-tools/IDEA.md`. Conventions mirror
+`~/code/telegram-tools` (v3.4.1) deliberately: same menu-vs-subcommand split,
+same test culture, same release recipe — when in doubt, look at the sibling.
+
+## Commands (v1 = full parity, built)
+
+auth (guided portal setup) · discover (server/channel/thread IDs) ·
+search/export (history fetch + local filter; Discord gives bots no search
+API) · send · create (channel/thread/category) · clear-messages · bot
+(settings + invite URL for the active profile) · doctor (token,
+message-content intent, servers, per-channel perms). v1 shipped 2026-08-27
+after the joint testing session.
+
+## Releasing (maintainer only)
+
+PyPI account is **banozz** (not the GitHub handle); the distribution is
+**discord-tools-cli** (`discord-tools` is squatted by an archived unrelated
+package) while the console script stays `discord-tools`. Recipe + traps: the
+maintainer's private runbook (same one as telegram-tools). Rebuild `dist/`
+after any source edit.
+
+## Working here
+
+- Python ≥3.11 · discord.py 2.x login-only REST (`client.py` is the one seam;
+  tests mock exactly it) · python-dotenv · pytest no-network · hatchling · MIT.
+- Test: `.venv/bin/python -m pytest -q` → all pass, no network, no real token.
+  CI adds `compileall` + per-subcommand `--help` smoke.
+- Bare invocation is the human menu; agents pass a subcommand.
+- Domain terms live in `CONTEXT.md`; read it before renaming things.
+- A CLI-surface change updates `skill/SKILL.md` in the same commit.
+- A user-visible fix gets its CHANGELOG entry + version bump in the same change.
+- Never commit tokens, IDs of real servers, or exported chat data. `.env*`
+  files (even `.env.example`) stay untracked — the global secrets hook blocks
+  them; setup docs live in the README instead.
+
+## Agent skills
+
+### Issue tracker
+
+Shared Beads board at `/Users/Shared/agent-board` (fleet default). See `docs/agents/issue-tracker.md`.
+
+### Triage labels
+
+Default five-role vocabulary, unchanged. See `docs/agents/triage-labels.md`.
+
+### Domain docs
+
+Single-context: `CONTEXT.md` + `docs/adr/` at the root. See `docs/agents/domain.md`.
+
+## Destructive commands
+
+Same gates as the sibling, non-negotiable: `clear-messages` dry-runs by
+default, executes only with `--execute` + typed `DELETE` (bulk API caps at
+14 days; older messages delete one-by-one, slower). `send` previews the full
+message + y/N; `--yes` requires the destination in `DISCORD_SEND_ALLOWLIST`
+(unset = refuse). `create` and `bot` settings confirm before touching anything
+real. The menu is never a shorter path past a gate.

discord_tools_cli-0.1.0/CHANGELOG.md

@@ -0,0 +1,33 @@
+# Changelog
+
+## 0.1.0 — 2026-08-27
+
+Initial release to telegram-tools parity (v1 contract in `SPEC.md`). Published
+as `discord-tools-cli` (the plain name is squatted on PyPI); the command is
+`discord-tools`:
+
+- `auth`: guided Developer Portal setup — walkthrough, hidden token paste,
+  live verification, message-content-intent re-check loop, invite URL with the
+  right permission bits, token stored per profile in `~/.discord-tools/.env`
+  (0600).
+- `doctor`: offline checks (Python, config, token shape, allowlist counts) and
+  live checks (login, message-content intent, joined servers); `--channel`
+  adds per-permission checks and an empty-content probe.
+- `discover`: server → channel → active-thread tree with IDs, `--server`,
+  `--json`.
+- `search`: paginated history fetch + local filtering (keyword, author, date
+  bounds, limit) with an early stop at `--since`; exports to JSON/CSV under
+  `~/.discord-tools/exports/` by default.
+- `send`: full-message preview + y/N; `--yes` gated by
+  `DISCORD_SEND_ALLOWLIST` (unset = refuse); attachment support with
+  pre-confirm existence checks.
+- `create channel|category|thread`: confirmation previews naming what will
+  exist where.
+- `clear-messages`: dry-run by default reporting the 14-day bulk/single split
+  from snowflake math; execution requires `--execute` + typed `DELETE`; bulk
+  endpoint for recent messages, paced one-by-one deletes beyond it.
+- `bot`: profile view (identity, description, avatar, intent, invite URL);
+  edits behind a diff + confirm; `--invite`.
+- Human menu on bare invocation mirroring telegram-tools; every destructive
+  action goes through the same gates as the flags.
+- Bundled agent skill (`skill/SKILL.md`).

discord_tools_cli-0.1.0/CLAUDE.md

@@ -0,0 +1 @@
+AGENTS.md

discord_tools_cli-0.1.0/CONTEXT.md

@@ -0,0 +1,40 @@
+# discord-tools — domain context
+
+The terms this codebase uses, and the boundaries they imply.
+
+- **Seam** — `DiscordClient` (`client.py`): the one boundary wrapping every
+  REST call. Everything above it (commands, menu, gates) works with plain
+  models and dicts; everything discord.py stays below it. Tests mock exactly
+  this interface (`tests/conftest.py::FakeClient`). Login-only: the gateway is
+  never connected.
+- **Profile** — a named bot token in `~/.discord-tools/.env`
+  (`DISCORD_BOT_TOKENS=name:token,...`). A bot per agent is the intended use.
+  `--profile` / `DISCORD_TOOLS_PROFILE` select one; `DISCORD_TOKEN` overrides.
+- **Gate** — the confirmation pattern on every destructive path, copied from
+  telegram-tools verbatim: send = preview + y/N (`--yes` needs the
+  allowlist), create = preview + y/N, clear = dry-run default + `--execute` +
+  typed `DELETE`, bot edits = diff + confirm. The menu builds the same args
+  the flags would and never sets `yes`/`execute` itself — it is never a
+  shorter path past a gate.
+- **Allowlist** — `DISCORD_SEND_ALLOWLIST`: channel/thread IDs an unattended
+  (`--yes`) send may target. Unset refuses everything; only the unattended
+  path consults it.
+- **Bulk window** — Discord's hard 14-day limit on the bulk-delete endpoint.
+  `split_bulk_window` (`delete.py`) partitions message IDs by snowflake
+  timestamp (pure math, no API calls); older messages delete one-by-one,
+  paced.
+- **Snowflake** — a Discord ID; its top bits encode a creation timestamp
+  (`records.py::snowflake_time`). Threads are channels: a thread ID is valid
+  anywhere a channel ID is.
+- **Intent (message-content)** — the portal toggle without which fetched
+  messages have empty `content`. Read from application flags
+  (`/applications/@me`); `auth` walks the user through enabling it, `doctor`
+  checks the flag and probes real messages for the symptom.
+- **Record** — the plain dict a message becomes (`records.py`): what search
+  prints and exports write. `has_media` keeps attachment-only messages from
+  reading as empty.
+- **Runner contract** — the menu calls `cli.run(args, client=..., config=...)`
+  with namespaces shaped exactly like parsed flags; a passed-in client is
+  owned by the caller and never closed by `run`.
+
+Architecture decisions with more context than fits here go to `docs/adr/`.

discord_tools_cli-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 telegram-tools contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

discord_tools_cli-0.1.0/PKG-INFO

@@ -0,0 +1,124 @@
+Metadata-Version: 2.5
+Name: discord-tools-cli
+Version: 0.1.0
+Summary: Local Discord bot CLI for server/channel/thread ID discovery, message search/export, sending, channel creation, message clearing, and bot settings — with a guided Developer Portal setup.
+Project-URL: Homepage, https://github.com/banozz0/discord-tools
+Project-URL: Repository, https://github.com/banozz0/discord-tools
+Project-URL: Issues, https://github.com/banozz0/discord-tools/issues
+Project-URL: Changelog, https://github.com/banozz0/discord-tools/blob/main/CHANGELOG.md
+License: MIT License
+        
+        Copyright (c) 2026 telegram-tools contributors
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Keywords: bot,channels,cli,discord,export,threads
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Communications :: Chat
+Classifier: Topic :: Utilities
+Requires-Python: >=3.11
+Requires-Dist: discord-py<3,>=2.4
+Requires-Dist: python-dotenv<2,>=1.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# discord-tools
+
+A local CLI for operating your Discord **bot**: discover server/channel/thread
+IDs, search and export messages, send messages, create channels and threads,
+clear messages, and manage the bot's settings — with a guided setup that walks
+you through the Discord Developer Portal (the BotFather it never had).
+
+Sibling of [telegram-tools](https://github.com/banozz0/telegram-tools): same
+menu for humans, same subcommands for agents, same safety gates on anything
+destructive. Bot-token auth only — no self-bots, ever (Discord ToS).
+
+## Install
+
+```bash
+pip install discord-tools-cli
+discord-tools auth      # guided bot setup: portal walkthrough, token check, invite URL
+discord-tools doctor    # verify token, message-content intent, servers, permissions
+```
+
+(The PyPI name is `discord-tools-cli` — plain `discord-tools` is squatted by an
+unrelated, archived package. The installed command is `discord-tools`.)
+
+Python 3.11+. Bare `discord-tools` opens a looping menu for humans; agents and
+scripts pass a subcommand.
+
+## Commands
+
+| Command | What it does |
+|---|---|
+| `auth` | Guided Developer Portal setup; verifies the token and the message-content intent, stores the token as a named profile, prints the invite URL |
+| `doctor` | Checks Python, config, token, intent, joined servers; `--channel <id>` adds per-channel permission checks and a message-visibility probe |
+| `discover` | Prints the server → channel → thread tree with every ID; `--server <id>` narrows, `--json <path>` writes a file |
+| `search` | Searches a channel/thread's history locally (Discord gives bots no search API): `--keyword`, `--from-user`, `--since`, `--until`, `--limit`; `--output <name>` exports JSON/CSV |
+| `send` | Posts as the bot after a full-message preview + y/N; `--yes` skips the prompt only for channels in `DISCORD_SEND_ALLOWLIST` |
+| `create` | `channel` / `category` / `thread`, each behind a confirmation |
+| `clear-messages` | Dry-run by default; deleting for real takes `--execute` **and** typing `DELETE`. The dry-run reports which messages fall inside Discord's 14-day bulk window and which will delete one-by-one (slower) |
+| `bot` | Shows the active profile's bot (username, description, avatar, intent, invite URL); edits go behind a diff + confirm |
+
+## Profiles: a bot per agent
+
+Tokens live in `~/.discord-tools/.env` (mode 0600) as named profiles:
+
+```
+DISCORD_BOT_TOKENS=default:token-a,dobby:token-b
+```
+
+`--profile dobby` (before the subcommand) selects one; `DISCORD_TOOLS_PROFILE`
+sets the default; `DISCORD_TOKEN` overrides everything. `auth` writes this
+file for you — run it once per bot.
+
+`DISCORD_SEND_ALLOWLIST` is a comma-separated list of channel/thread IDs that
+`send --yes` may post to. Unset means every unattended send is refused — each
+destination is opted in by hand.
+
+## Exports stay out of your repos
+
+Relative `--output` names land in `~/.discord-tools/exports/`, never the
+working directory. Message text coming back empty on every message means the
+**message-content intent** is off in the portal — `doctor` names it and `auth`
+walks you through enabling it.
+
+## For agents
+
+`skill/SKILL.md` is a bundled agent skill describing the CLI surface and the
+rules an agent must follow (never `clear-messages`, allowlist-gated sends,
+never print tokens). It updates in the same commit as any CLI-surface change.
+
+## Development
+
+```bash
+python -m venv .venv && .venv/bin/pip install -e ".[dev]"
+.venv/bin/python -m pytest    # no network, no real token
+```
+
+MIT. See `SPEC.md` for the v1 contract and `CHANGELOG.md` for history.

discord_tools_cli-0.1.0/README.md

@@ -0,0 +1,75 @@
+# discord-tools
+
+A local CLI for operating your Discord **bot**: discover server/channel/thread
+IDs, search and export messages, send messages, create channels and threads,
+clear messages, and manage the bot's settings — with a guided setup that walks
+you through the Discord Developer Portal (the BotFather it never had).
+
+Sibling of [telegram-tools](https://github.com/banozz0/telegram-tools): same
+menu for humans, same subcommands for agents, same safety gates on anything
+destructive. Bot-token auth only — no self-bots, ever (Discord ToS).
+
+## Install
+
+```bash
+pip install discord-tools-cli
+discord-tools auth      # guided bot setup: portal walkthrough, token check, invite URL
+discord-tools doctor    # verify token, message-content intent, servers, permissions
+```
+
+(The PyPI name is `discord-tools-cli` — plain `discord-tools` is squatted by an
+unrelated, archived package. The installed command is `discord-tools`.)
+
+Python 3.11+. Bare `discord-tools` opens a looping menu for humans; agents and
+scripts pass a subcommand.
+
+## Commands
+
+| Command | What it does |
+|---|---|
+| `auth` | Guided Developer Portal setup; verifies the token and the message-content intent, stores the token as a named profile, prints the invite URL |
+| `doctor` | Checks Python, config, token, intent, joined servers; `--channel <id>` adds per-channel permission checks and a message-visibility probe |
+| `discover` | Prints the server → channel → thread tree with every ID; `--server <id>` narrows, `--json <path>` writes a file |
+| `search` | Searches a channel/thread's history locally (Discord gives bots no search API): `--keyword`, `--from-user`, `--since`, `--until`, `--limit`; `--output <name>` exports JSON/CSV |
+| `send` | Posts as the bot after a full-message preview + y/N; `--yes` skips the prompt only for channels in `DISCORD_SEND_ALLOWLIST` |
+| `create` | `channel` / `category` / `thread`, each behind a confirmation |
+| `clear-messages` | Dry-run by default; deleting for real takes `--execute` **and** typing `DELETE`. The dry-run reports which messages fall inside Discord's 14-day bulk window and which will delete one-by-one (slower) |
+| `bot` | Shows the active profile's bot (username, description, avatar, intent, invite URL); edits go behind a diff + confirm |
+
+## Profiles: a bot per agent
+
+Tokens live in `~/.discord-tools/.env` (mode 0600) as named profiles:
+
+```
+DISCORD_BOT_TOKENS=default:token-a,dobby:token-b
+```
+
+`--profile dobby` (before the subcommand) selects one; `DISCORD_TOOLS_PROFILE`
+sets the default; `DISCORD_TOKEN` overrides everything. `auth` writes this
+file for you — run it once per bot.
+
+`DISCORD_SEND_ALLOWLIST` is a comma-separated list of channel/thread IDs that
+`send --yes` may post to. Unset means every unattended send is refused — each
+destination is opted in by hand.
+
+## Exports stay out of your repos
+
+Relative `--output` names land in `~/.discord-tools/exports/`, never the
+working directory. Message text coming back empty on every message means the
+**message-content intent** is off in the portal — `doctor` names it and `auth`
+walks you through enabling it.
+
+## For agents
+
+`skill/SKILL.md` is a bundled agent skill describing the CLI surface and the
+rules an agent must follow (never `clear-messages`, allowlist-gated sends,
+never print tokens). It updates in the same commit as any CLI-surface change.
+
+## Development
+
+```bash
+python -m venv .venv && .venv/bin/pip install -e ".[dev]"
+.venv/bin/python -m pytest    # no network, no real token
+```
+
+MIT. See `SPEC.md` for the v1 contract and `CHANGELOG.md` for history.

discord_tools_cli-0.1.0/SPEC.md

@@ -0,0 +1,117 @@
+# discord-tools v1 — spec
+
+Graduated from incubator shaping 2026-08-27. Decision record:
+`~/code/incubator/discord-tools/IDEA.md`. Sibling and convention source:
+`~/code/telegram-tools` (v3.4.1).
+
+## Problem Statement
+
+Sven and his agents operate Discord the way they already operate Telegram:
+finding channel/thread IDs, searching and exporting history, sending messages,
+creating channels, clearing messages, managing bots. On Discord there is no
+telegram-tools equivalent — every one of those tasks means clicking through the
+Discord app or hand-rolling API calls, and the bot setup itself (Developer
+Portal, intents, permission bits, invite URLs) is a maze with no BotFather to
+talk to. Discord also bans self-bots, so the Telethon approach cannot be
+ported directly.
+
+## Solution
+
+A local Python CLI, `discord-tools`, that is a deliberate sibling of
+telegram-tools: bare invocation opens a human menu, agents pass subcommands,
+`--json` where structure helps. It authenticates as a **bot** (ToS-safe, never
+a user token), with a guided setup that walks through the Developer Portal and
+verifies the result — the guided setup is the BotFather replacement. All seven
+telegram-tools functions ship in v1, mapped to what a bot can legally do, with
+the same safety gates on anything destructive. Named token profiles support a
+bot per agent.
+
+## User Stories
+
+1. As a new user, I want a guided `auth` setup that walks me through creating a Discord application, enabling the message-content intent, and generating the invite URL, so that I get from zero to a working bot without reading Discord docs.
+2. As a user, I want `doctor` to verify my token, intents, joined servers, and per-channel permissions, so that I know exactly what is misconfigured when something fails.
+3. As an agent operator, I want named token profiles in `~/.discord-tools/` with `--profile <name>` and an env-var override, so that each of my agents runs as its own bot.
+4. As an agent, I want `discover` to print the full server → channel → thread tree with IDs, so that I can address any destination without a human copying IDs from the app.
+5. As an agent, I want `--json` output on read commands, so that I can parse results without scraping human-formatted text.
+6. As a user, I want `search` to find messages by keyword/sender/date in a channel, so that I can locate a conversation without scrolling Discord.
+7. As a user, I want `export` to write a channel or thread's history to a local file (JSON/CSV), so that I own a searchable archive outside Discord.
+8. As a user, I want exports to land under `~/.discord-tools/exports/` and never inside a repo, so that chat data cannot leak into version control.
+9. As an agent, I want `send` to post a message to a channel or thread as the bot, so that automations can report into Discord.
+10. As a user, I want `send` to preview the full message and ask y/N before posting, so that nothing goes public by accident.
+11. As an agent operator, I want `send --yes` to work only for destinations on an explicit allowlist (unset = refuse), so that unattended sends are constrained to channels I chose.
+12. As a user, I want `create` to make channels, threads, and categories behind a confirmation, so that I can scaffold a server without the app and without accidental objects.
+13. As a user, I want `clear-messages` to dry-run by default, listing what would be deleted, so that I can see the blast radius before anything happens.
+14. As a user, I want `clear-messages` execution to require `--execute` plus typing `DELETE`, so that real deletion is never one keystroke away.
+15. As a user, I want the dry-run to tell me which messages fall inside the 14-day bulk-delete window and which will delete one-by-one (slower), so that I know what to expect before confirming.
+16. As a user, I want `bot` to show and edit the active profile's name, avatar, and description behind a diff + confirm, so that I manage bot identity without the portal.
+17. As a user, I want `bot` to print the invite URL with the right permission bits, so that adding the bot to another server is copy-paste.
+18. As a human, I want bare `discord-tools` to open the same menu style as telegram-tools, so that I never memorize subcommands.
+19. As a telegram-tools user, I want the menus, flags, and gate behavior to feel identical, so that I carry my habits over with zero relearning.
+20. As an agent, I want a bundled skill (`skill/SKILL.md`) describing the CLI surface, so that any Claude session can drive the tool correctly.
+21. As a contributor, I want the test suite to run with no network and no real token, so that CI and local runs are safe and fast.
+22. As a user, I want clear errors when the message-content intent is off (content comes back empty), so that the classic silent-empty-export trap is named instead of mysterious.
+23. As a user, I want rate limits handled with pacing and retry, so that big exports and slow deletes finish instead of erroring.
+24. As a security-conscious user, I want the token stored 0600 and never printed, committed, or logged, so that a leaked terminal scroll never leaks the bot.
+
+## Implementation Decisions
+
+- Python ≥3.11; dependencies mirror the sibling's minimalism: discord.py 2.x
+  and python-dotenv only. discord.py is used **login-only / REST** (no gateway
+  loop) for its rate-limit handling and typed models; if login-only REST
+  fights the one-shot CLI shape, the fallback decision is a thin httpx client
+  behind the same internal interface.
+- One internal seam: a `DiscordClient` boundary wrapping every REST call the
+  CLI makes. The menu, subcommands, exporters, and gates all sit above it;
+  tests mock exactly this seam. This mirrors telegram-tools' client boundary.
+- Auth is bot-token only. No user-token code path exists anywhere — not even
+  behind a flag (ToS; decided in shaping, non-negotiable).
+- Config: `~/.discord-tools/` with named profiles; file mode 0600; env var
+  override for token and profile selection; python-dotenv for local dev.
+- `search` is a local filter over fetched history — Discord exposes no search
+  API to bots. Search and export share the paginated history-fetch path.
+- `clear-messages` uses the bulk endpoint for messages <14 days old (API hard
+  limit) and one-by-one deletion beyond it; dry-run computes both buckets from
+  snowflake timestamps without extra API calls.
+- Destructive gates copy the sibling verbatim: dry-run default + `--execute` +
+  typed `DELETE` for clears; full preview + y/N for send; allowlist env
+  (`DISCORD_SEND_ALLOWLIST`) required for `--yes` sends; diff + confirm for
+  bot settings; confirm before create. The menu never bypasses a gate.
+- CLI structure mirrors telegram-tools: bare invocation = menu; subcommands
+  for agents; `--json` on read commands; per-subcommand `--help`.
+- Packaging: hatchling, MIT, console script `discord-tools`, PyPI under the
+  banozz account, same release recipe and CHANGELOG discipline as the sibling.
+- `skill/SKILL.md` is independently versioned and updated in the same commit
+  as any CLI-surface change.
+- No gateway connection, no event listening, no slash-command registration in
+  v1 — the bot is a REST actor driven by the CLI.
+
+## Testing Decisions
+
+- pytest, no network, no real token — the entire suite runs against a mocked
+  `DiscordClient` seam. Test external behavior (CLI output, files written,
+  refusals) — never internals.
+- Prior art: telegram-tools' suite (339 no-network tests) is the model; CI
+  additionally runs `compileall` and a per-subcommand `--help` smoke.
+- Gate tests are mandatory: clear without `--execute` deletes nothing; wrong
+  typed confirmation aborts; `send --yes` without allowlist refuses; every
+  destructive path has a refusal test before a success test.
+- The 14-day split logic is pure (snowflake math) and gets direct unit tests.
+- Export tests verify file shape (JSON/CSV) and that exports never land in
+  the working directory.
+
+## Out of Scope
+
+- The localhost web dashboard (parked as a later phase in shaping).
+- Self-bot / user-token operation, in any form, ever.
+- Real-time features: gateway events, message listening, slash commands,
+  voice, presence.
+- DM reading or sending as the user (a bot cannot act as Sven).
+- SQLite storage (revisit only if the dashboard phase needs it).
+
+## Further Notes
+
+- Verify during Phase 1 whether the message-content intent gates REST history
+  fetches the same way it gates gateway payloads, and make `doctor` test for
+  the empty-content symptom directly.
+- v1 is done only after the joint testing session with Sven covering every
+  command (shaping decision), then the PyPI release.

discord_tools_cli-0.1.0/docs/agents/domain.md

@@ -0,0 +1,51 @@
+# Domain Docs
+
+How the engineering skills should consume this repo's domain documentation when exploring the codebase.
+
+## Before exploring, read these
+
+- **`CONTEXT.md`** at the repo root, or
+- **`CONTEXT-MAP.md`** at the repo root if it exists: it points at one `CONTEXT.md` per context. Read each one relevant to the topic.
+- **`docs/adr/`**: read ADRs that touch the area you're about to work in. In multi-context repos, also check `src/<context>/docs/adr/` for context-scoped decisions.
+
+If any of these files don't exist, **proceed silently**. Don't flag their absence; don't suggest creating them upfront. The `/domain-modeling` skill (reached via `/grill-with-docs` and `/improve-codebase-architecture`) creates them lazily when terms or decisions actually get resolved.
+
+## File structure
+
+Single-context repo (most repos):
+
+```
+/
+├── CONTEXT.md
+├── docs/adr/
+│   ├── 0001-event-sourced-orders.md
+│   └── 0002-postgres-for-write-model.md
+└── src/
+```
+
+Multi-context repo (presence of `CONTEXT-MAP.md` at the root):
+
+```
+/
+├── CONTEXT-MAP.md
+├── docs/adr/                          ← system-wide decisions
+└── src/
+    ├── ordering/
+    │   ├── CONTEXT.md
+    │   └── docs/adr/                  ← context-specific decisions
+    └── billing/
+        ├── CONTEXT.md
+        └── docs/adr/
+```
+
+## Use the glossary's vocabulary
+
+When your output names a domain concept (in an issue title, a refactor proposal, a hypothesis, a test name), use the term as defined in `CONTEXT.md`. Don't drift to synonyms the glossary explicitly avoids.
+
+If the concept you need isn't in the glossary yet, that's a signal: either you're inventing language the project doesn't use (reconsider) or there's a real gap (note it for `/domain-modeling`).
+
+## Flag ADR conflicts
+
+If your output contradicts an existing ADR, surface it explicitly rather than silently overriding:
+
+> _Contradicts ADR-0007 (event-sourced orders), but worth reopening because…_

discord_tools_cli-0.1.0/docs/agents/issue-tracker.md

@@ -0,0 +1,19 @@
+# Issue Tracker
+
+Issues for this repo live on the shared **Beads board** at
+`/Users/Shared/agent-board` — the fleet-wide queue Claude Code, Codex, and
+Hermes all read and write (via `bd` or the `beads` MCP tools).
+
+- Skills that "create an issue" (`to-tickets`, `to-spec`, `triage`) create a
+  bead, written per canon `board-writing.md` (agent-config repo): 2–5 word
+  title, two-zone description (≤8 human lines then a `🤖 For the agent` brief),
+  no Markdown syntax, every card names an assignee (the worker, never the
+  writer).
+- Blocking edges: `bd dep add`.
+- Claim atomically before working a card; link your session with
+  `gx board associate <id>`.
+- Repo-scoping: prefix titles or use the board's project field with
+  `discord-tools` so the repo's cards are findable.
+
+PRs as a request surface: **off**. External PRs are not part of the triage
+queue for this repo.

discord_tools_cli-0.1.0/docs/agents/triage-labels.md

@@ -0,0 +1,15 @@
+# Triage Labels
+
+The skills speak in terms of five canonical triage roles. This file maps those roles to the actual label strings used in this repo's issue tracker.
+
+| Label in mattpocock/skills | Label in our tracker | Meaning                                  |
+| -------------------------- | -------------------- | ---------------------------------------- |
+| `needs-triage`             | `needs-triage`       | Maintainer needs to evaluate this issue  |
+| `needs-info`               | `needs-info`         | Waiting on reporter for more information |
+| `ready-for-agent`          | `ready-for-agent`    | Fully specified, ready for an AFK agent  |
+| `ready-for-human`          | `ready-for-human`    | Requires human implementation            |
+| `wontfix`                  | `wontfix`            | Will not be actioned                     |
+
+When a skill mentions a role (e.g. "apply the AFK-ready triage label"), use the corresponding label string from this table.
+
+Edit the right-hand column to match whatever vocabulary you actually use.