@drewpayment/mink 0.3.0 → 0.5.0

package/README.md

@@ -21,6 +21,8 @@ Mink intercepts these lifecycle events and maintains structured state so the ass
 - **Advise on frameworks** with a decision tree and migration guides
 - **Build a cross-project wiki** that accumulates knowledge across all your projects
 - **Capture notes from anywhere** with an AI-powered Claude Code skill that categorizes, tags, and links notes automatically
+- **Chat with Mink from Discord** — DM your bot to capture, search, and summarize your wiki from anywhere via Claude Code Channels
+- **Sync across machines** with git-backed `~/.mink` syncing — auto-pull on session start, auto-push on session stop
 
 ## How It Works
 
@@ -69,9 +71,15 @@ All state lives in `~/.mink/` -- nothing is stored in your project repository.
 - **Claude Code Skill** — `/mink:note` skill uses Claude as the AI brain for intelligent categorization, tagging, and wikilink insertion
 - **Daily Notes** — `mink note --daily` creates or appends to daily journal entries
 - **Vault Index** — Token-efficient file index for the vault, with search and tag aggregation
-- **Git Backup** — Auto-commit and push vault changes on session end
+- **External Linking** — Symlink external notes directories into the vault for a unified Obsidian experience
 - **Templates** — 6 built-in templates (quick-capture, daily, meeting, project, area, person)
 
+### Discord Companion
+- **Conversational interface** — DM your bot on Discord to capture notes, search the vault, and get daily summaries
+- **Always-on** — runs Claude Code inside a detached GNU screen session that survives terminal closes
+- **CLAUDE.md-driven persona** — the bot's behavior is configured by a markdown file in the vault, not code
+- **Unattended mode** — optional `--dangerously-skip-permissions` bypasses terminal prompts so the bot works entirely from Discord
+
 ### Advanced
 - **Design Evaluation** — Automated multi-viewport screenshot capture with server and route detection (uses Puppeteer)
 - **Framework Advisor** — Decision tree, framework catalog, comparison matrix, and migration prompts for UI framework selection
@@ -249,19 +257,225 @@ The vault is a standard markdown directory fully compatible with Obsidian:
 
 Open the vault directory as an Obsidian vault and everything works out of the box.
 
-### Git backup
+### Link external notes
+
+If you already have a notes repository, you can symlink it into the vault so everything appears together in Obsidian:
+
+```bash
+# Symlink your existing notes into the vault
+mink wiki link ~/dev/notes
+
+# Result: ~/.mink/wiki/notes -> ~/dev/notes
+
+# Custom name
+mink wiki link ~/dev/notes my-notes
+
+# List linked directories
+mink wiki links
+
+# Remove a link (original directory is untouched)
+mink wiki unlink notes
+```
+
+Open `~/.mink/wiki/` as your Obsidian vault and you'll see Mink's generated content (projects, patterns, inbox) alongside your own notes — with `[[wikilinks]]` working across both.
+
+## Discord Companion
+
+DM your bot on Discord to capture notes, search the vault, and get summaries — with the Claude Code session running on your own machine against your own wiki.
+
+This uses [Claude Code Channels](https://code.claude.com/docs/en/channels) to push Discord messages into a running Claude Code session. The session launches inside a detached GNU screen with a preloaded `CLAUDE.md` that makes Claude behave as a knowledge companion. Nothing is hosted; the bot is just you talking to Claude on your laptop.
+
+### Prerequisites
+
+- [Claude Code](https://claude.ai/code) v2.1.80+ signed in with a `claude.ai` account (Console/API-key auth is not supported by Channels)
+- [Bun](https://bun.sh/) (required by the Discord channel plugin)
+- `screen` (pre-installed on macOS; `sudo apt install screen` on Linux)
+- An initialized vault: `mink wiki init`
+
+### Step-by-step setup
+
+**1. Create a Discord bot**
+
+In the [Discord Developer Portal](https://discord.com/developers/applications):
+
+1. Click **New Application** and give it a name
+2. Open the **Bot** page → click **Reset Token** → copy the token somewhere safe
+3. On the same page, scroll to **Privileged Gateway Intents** and enable **Message Content Intent** (required — without this the bot receives empty messages)
+
+**2. Invite the bot to a server**
+
+Still in the Developer Portal:
+
+1. Go to **OAuth2 → URL Generator**
+2. Set **Integration Type** to **Guild Install** (not *User Install* — `bot` scope is only valid for Guild Install)
+3. Check scope: **bot**
+4. Check bot permissions: **View Channels**, **Send Messages**, **Send Messages in Threads**, **Read Message History**, **Attach Files**, **Add Reactions**
+5. Open the generated URL in your browser and invite the bot to a server
+
+> To DM the bot privately, create a personal server first (Discord → `+` icon → **Create My Own** → *For me and my friends*). Guild-Install bots can receive DMs from any user who shares a server with them.
+
+**3. Install the Discord channel plugin in Claude Code (one time)**
+
+```bash
+claude
+```
+
+Inside Claude Code:
+
+```
+/plugin install discord@claude-plugins-official
+```
+
+Wait for the confirmation, then exit Claude Code.
+
+**4. Save the bot token in mink**
+
+```bash
+mink channel setup discord --token YOUR_BOT_TOKEN
+```
+
+Running `mink channel setup discord` without `--token` prints the full instructions above for reference. The token is stored in `~/.mink/config.local` (machine-scoped — it won't sync to other machines).
+
+**5. Start the channel**
+
+```bash
+mink channel start
+```
+
+This:
 
-Enable automatic git backup to sync your vault across machines:
+- Writes `~/.mink/wiki/CLAUDE.md` (the companion personality) if it doesn't already exist
+- Launches Claude Code with `--channels plugin:discord@claude-plugins-official --dangerously-skip-permissions` inside a detached GNU screen session named `mink-channel-discord`
+
+**6. Pair your Discord account**
+
+1. DM your bot on Discord (any message)
+2. The bot replies with a pairing code
+3. Attach to the session so you can type into Claude Code:
+   ```bash
+   mink channel attach
+   ```
+4. Inside the attached session, run:
+   ```
+   /discord:access pair YOUR_PAIRING_CODE
+   /discord:access policy allowlist
+   ```
+5. Detach with **Ctrl-a** then **d** (don't exit — detach keeps the session running)
+
+You're done. DM your bot from anywhere.
+
+### Daily use
 
 ```bash
-# Enable git backup
-mink config wiki.git-backup true
+mink channel status     # running? uptime? session name?
+mink channel logs       # recent Claude Code output (via screen hardcopy)
+mink channel attach     # jump into the live session; detach with Ctrl-a d
+mink channel stop       # end the session
+mink channel start      # start it again (e.g. after a reboot)
+```
+
+### Example conversations
+
+From Discord:
+
+- **Capture** — "Save a note — the auth migration is blocked on new compliance requirements from legal."
+- **Daily** — "Add to my daily: shipped the config refactor, PR #42 is up."
+- **Meeting** — "Meeting with Sarah about Q3 roadmap — discussed prioritizing the mobile SDK, 6-week timeline."
+- **Search** — "What did I write about the auth migration?"
+- **Summary** — "What did I work on this week?"
+
+The companion `CLAUDE.md` tells Claude to categorize, tag with existing vocabulary, add `[[wikilinks]]`, and reply briefly.
+
+### Customizing the bot's personality
+
+The bot's behavior lives in `~/.mink/wiki/CLAUDE.md` — pure markdown, no code. Edit it to adjust tone, add behavioral rules, or include project-specific context. Changes take effect on the next `mink channel start`.
 
-# Set the remote (default: origin)
-mink config wiki.git-remote origin
+Mink never overwrites an existing `CLAUDE.md`. To refresh from the built-in template after a mink upgrade:
+
+```bash
+rm ~/.mink/wiki/CLAUDE.md
+mink channel start
 ```
 
-When enabled, Mink auto-commits and pushes vault changes at the end of each session. Pushes are best-effort with a 10-second timeout — if the push fails, the local commit is preserved and will be included in the next push.
+### Configuration
+
+| Setting | Default | Scope | Description |
+|---------|---------|-------|-------------|
+| `channel.discord.bot-token` | — | local | Discord bot token (saved by `mink channel setup`) |
+| `channel.discord.enabled` | `false` | local | Auto-start the channel when `mink daemon start` runs |
+| `channel.default-platform` | `discord` | shared | Platform when `mink channel start` is run without an argument |
+| `channel.skip-permissions` | `true` | shared | Pass `--dangerously-skip-permissions` so the bot runs unattended |
+
+Change any value with `mink config <key> <value>`.
+
+### Security model
+
+- **Sender allowlist** — After pairing and running `/discord:access policy allowlist`, only your Discord account can push messages to the bot. Everyone else is silently dropped.
+- **Local execution** — The Claude Code session runs entirely on your own machine. Nothing is hosted.
+- **Skip-permissions trade-off** — With `channel.skip-permissions` on (default), Claude does not prompt before tool calls. Combined with the sender allowlist this is fine for personal use; turn it off with `mink config channel.skip-permissions false` if you want each tool call approved via `mink channel attach`.
+- **Scope** — The companion `CLAUDE.md` tells Claude to stay focused on vault/mink operations and not edit source code.
+
+### Troubleshooting
+
+- **"channel session died immediately after starting"** — Usually `claude` isn't on your PATH, or the Discord plugin isn't installed. Run `which claude` and verify step 3 (`/plugin install discord@claude-plugins-official`) was completed. To see the underlying error, run the command manually:
+  ```bash
+  cd ~/.mink/wiki && claude --channels plugin:discord@claude-plugins-official
+  ```
+- **Bot doesn't respond to DMs** — Make sure you share a server with it (Guild-Install bots can only DM users who share a server) and that **Message Content Intent** is enabled in the Developer Portal.
+- **`Input must be provided either through stdin...`** in logs — The Claude Code session has no TTY. The `mink channel` commands spawn through GNU screen to avoid this; if you see it, check that `screen` is on PATH.
+- **Permission prompts stall the bot** — Ensure `mink config channel.skip-permissions` is `true` (the default). Apply after a restart: `mink channel stop && mink channel start`.
+- **Token rotated or invalid** — Re-run `mink channel setup discord --token NEW_TOKEN`, then restart the channel.
+- **Colors look washed out when you `mink channel attach`** — mink starts screen with `-T screen-256color` so Claude Code renders at 256-color depth. If you still see muted output, verify your terminfo database has the entry: `infocmp screen-256color`. If truecolor escape codes look garbled (common on very old GNU screen versions like macOS's bundled 4.00.03), restart the channel with `COLORTERM` unset so Claude falls back to 256-color mode: `mink channel stop && env -u COLORTERM mink channel start`.
+
+## Sync
+
+Mink can sync your entire `~/.mink` directory (wiki, config, project knowledge) across machines using git.
+
+### Set up sync
+
+```bash
+# Initialize sync with a remote repository
+mink sync init git@github.com:you/mink-data.git
+```
+
+This initializes git in `~/.mink`, sets the remote, and creates a `.gitignore` that excludes machine-specific state (PIDs, logs, backups).
+
+### Automatic sync
+
+Once initialized, sync happens automatically:
+
+- **Session start** — pulls remote changes (rebase-based, preserves local work)
+- **Session stop** — commits and pushes local changes
+
+No manual intervention needed. Your wiki, config, learning memory, and bug history stay in sync.
+
+### Manual sync
+
+```bash
+# Full sync (pull then push)
+mink sync
+
+# Individual operations
+mink sync pull
+mink sync push
+
+# Check sync state
+mink sync status
+
+# Temporarily disable auto-sync
+mink sync pause
+mink sync resume
+
+# Remove git tracking (data preserved)
+mink sync disconnect
+```
+
+### Conflict handling
+
+- Pull uses stash + rebase to preserve local changes
+- If a rebase conflict occurs, the rebase is aborted and you're warned to resolve manually
+- Push failures preserve the local commit — it will be included in the next push
+- Git operations have timeouts (5-15s) so they never block your session
 
 ### Hook integration
 
@@ -292,9 +506,11 @@ mink config notes.default-category inbox
 | `wiki.path` | `~/.mink/wiki/` | `MINK_WIKI_PATH` | Vault directory |
 | `wiki.enabled` | `true` | `MINK_WIKI_ENABLED` | Toggle wiki feature |
 | `wiki.sync-mode` | `immediate` | `MINK_WIKI_SYNC_MODE` | Update timing |
-| `wiki.git-backup` | `false` | `MINK_WIKI_GIT_BACKUP` | Auto-commit and push |
-| `wiki.git-remote` | `origin` | `MINK_WIKI_GIT_REMOTE` | Git remote for push |
 | `notes.default-category` | `inbox` | `MINK_NOTES_DEFAULT_CATEGORY` | Default note category |
+| `sync.enabled` | `false` | — | Enable git sync for ~/.mink |
+| `sync.remote-url` | — | — | Git remote URL for sync |
+| `sync.last-push` | — | — | Timestamp of last push |
+| `sync.last-pull` | — | — | Timestamp of last pull |
 
 ## Architecture
 
@@ -379,7 +595,7 @@ mink/
 │   │   ├── post-read.ts      # Hook: post-read tracking
 │   │   ├── pre-write.ts      # Hook: write enforcement
 │   │   ├── post-write.ts     # Hook: post-write tracking
-│   │   ├── wiki.ts           # Wiki vault management (init, status, rebuild, organize)
+│   │   ├── wiki.ts           # Wiki vault management (init, status, link, unlink, rebuild, organize)
 │   │   ├── note.ts           # Note capture, list, and search
 │   │   ├── skill.ts          # Claude Code skill installer
 │   │   ├── status.ts         # Project health display
@@ -421,6 +637,7 @@ mink/
 │   │   ├── note-writer.ts    # Note creation, frontmatter, daily notes
 │   │   ├── note-linker.ts    # Wikilink extraction, insertion, backlinks
 │   │   ├── note-index.ts     # Vault file index with search
+│   │   ├── sync.ts           # Git-based ~/.mink sync engine
 │   │   └── ...               # Global config, backup, reflection, etc.
 │   ├── dashboard/            # Embedded dashboard UI (HTML/CSS/JS generation)
 │   │   ├── get-dashboard-html.ts  # Main HTML assembly
@@ -491,6 +708,13 @@ bun src/cli.ts note --daily "Today I worked on mink"
 bun src/cli.ts note list --recent 5
 bun src/cli.ts note search "testing"
 
+# Link external notes into the vault
+bun src/cli.ts wiki link ~/dev/notes
+
+# Set up cross-device sync
+bun src/cli.ts sync init git@github.com:you/mink-data.git
+bun src/cli.ts sync status
+
 # Install the Claude Code skill
 bun src/cli.ts skill install
 ```