121 lines
2.7 KiB
Markdown
121 lines
2.7 KiB
Markdown
# TOOLS.md — Tool Reference & Gotchas
|
|
|
|
**Purpose:** Document tools you use and their quirks. Save future-you hours of rediscovery.
|
|
|
|
---
|
|
|
|
## How to Use This File
|
|
|
|
When you learn something about a tool that isn't obvious:
|
|
1. Add it here immediately
|
|
2. Include the gotcha, workaround, and example
|
|
3. Reference this file before using tools
|
|
|
|
---
|
|
|
|
## Tool Template
|
|
|
|
```markdown
|
|
### [Tool Name]
|
|
|
|
**What it does:** [Brief description]
|
|
**Documentation:** [Link]
|
|
|
|
**Setup:**
|
|
- [Step 1]
|
|
- [Step 2]
|
|
|
|
**Common Commands:**
|
|
| Command | What It Does |
|
|
|---------|--------------|
|
|
| `command` | Description |
|
|
|
|
**Gotchas:**
|
|
- ⚠️ [Thing that's not obvious]
|
|
- ⚠️ [Common mistake to avoid]
|
|
|
|
**Examples:**
|
|
\`\`\`bash
|
|
# Example usage
|
|
command --flag value
|
|
\`\`\`
|
|
```
|
|
|
|
---
|
|
|
|
## Installed Tools
|
|
|
|
[Add your tools below as you learn their quirks]
|
|
|
|
---
|
|
|
|
### Example: Discord Bot
|
|
|
|
**What it does:** Send/read messages in Discord servers
|
|
**Documentation:** [Your bot docs]
|
|
|
|
**Common Commands:**
|
|
| Command | What It Does |
|
|
|---------|--------------|
|
|
| `message action=read channel=discord channelId=ID limit=15` | Read recent messages |
|
|
| `message action=send channel=discord channelId=ID content="text"` | Send message |
|
|
|
|
**Gotchas:**
|
|
- ⚠️ Use channel IDs, not names (names can change)
|
|
- ⚠️ Bot must have permissions in the channel
|
|
- ⚠️ "Missing Access" usually means permission issue, not bot offline
|
|
- ⚠️ Rate limits: Don't spam reads/sends
|
|
|
|
**Troubleshooting:**
|
|
| Error | Cause | Fix |
|
|
|-------|-------|-----|
|
|
| Missing Access | No permission | Check bot role in server settings |
|
|
| Unknown Channel | Wrong ID | Verify channel ID in Discord |
|
|
| Rate Limited | Too many requests | Wait and retry |
|
|
|
|
---
|
|
|
|
### Example: Google Calendar
|
|
|
|
**What it does:** Read/write calendar events
|
|
**Documentation:** [Link]
|
|
|
|
**Common Commands:**
|
|
| Command | What It Does |
|
|
|---------|--------------|
|
|
| `gog calendar list --account email` | List today's events |
|
|
| `gog calendar create --account email --title "Meeting"` | Create event |
|
|
|
|
**Gotchas:**
|
|
- ⚠️ Always specify `--account` flag
|
|
- ⚠️ Times are in account's timezone unless specified
|
|
- ⚠️ OAuth token expires — may need to re-auth
|
|
|
|
---
|
|
|
|
## API Keys & Credentials
|
|
|
|
**DO NOT store actual credentials here.**
|
|
|
|
| Service | Location | Notes |
|
|
|---------|----------|-------|
|
|
| [Service] | Environment variable: `VAR_NAME` | [Notes] |
|
|
| [Service] | Secrets manager path | [Notes] |
|
|
|
|
---
|
|
|
|
## Tool Wishlist
|
|
|
|
Tools you want but don't have yet:
|
|
|
|
- [ ] [Tool name] — [What it would help with]
|
|
- [ ] [Tool name] — [What it would help with]
|
|
|
|
---
|
|
|
|
*Update this file whenever you learn something about a tool.*
|
|
|
|
---
|
|
|
|
*Part of AI Persona OS by Jeff J Hunter — https://os.aipersonamethod.com*
|