diff options
| author | Paul Buetow <paul@buetow.org> | 2026-02-11 20:53:45 +0200 |
|---|---|---|
| committer | Paul Buetow <paul@buetow.org> | 2026-02-11 20:53:45 +0200 |
| commit | a82d0b061a02fd395de293353386d0b16cbe6b18 (patch) | |
| tree | 55ac689596267b43d5dbcdc608cfc23472c2faf8 /docs | |
| parent | 8312a19b4e1f9849aae9912433824b19e03a8daf (diff) | |
docs: update all paths to consolidated .local/hexai directory
Update all documentation to reflect new directory structure:
- Cache: ~/.local/hexai/cache/
- State: ~/.local/hexai/state/
- Data: ~/.local/hexai/data/
Updated files:
- README.md
- docs/mcp-setup.md
- docs/mcp-prompts.md
- docs/mcp-managing-prompts.md
- docs/mcp-features-summary.md
- docs/mcp-automatic-backups.md
- docs/mcp-server-complete.md
Amp-Thread-ID: https://ampcode.com/threads/T-019c4e03-73db-70a2-ae27-3e1cc31d59c3
Co-authored-by: Amp <amp@ampcode.com>
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/mcp-automatic-backups.md | 8 | ||||
| -rw-r--r-- | docs/mcp-features-summary.md | 10 | ||||
| -rw-r--r-- | docs/mcp-managing-prompts.md | 42 | ||||
| -rw-r--r-- | docs/mcp-prompts.md | 10 | ||||
| -rw-r--r-- | docs/mcp-server-complete.md | 14 | ||||
| -rw-r--r-- | docs/mcp-setup.md | 14 |
6 files changed, 49 insertions, 49 deletions
diff --git a/docs/mcp-automatic-backups.md b/docs/mcp-automatic-backups.md index ccc0734..87ec329 100644 --- a/docs/mcp-automatic-backups.md +++ b/docs/mcp-automatic-backups.md @@ -57,7 +57,7 @@ Every operation through the MCP server automatically creates a backup: ### Storage Location ``` -~/.local/share/hexai/prompts/backups/ +~/.local/hexai/data/prompts/backups/ ├── user.jsonl.20260210-190358 ├── user.jsonl.20260210-192145 ├── user.jsonl.20260210-193422 @@ -122,7 +122,7 @@ In rare cases where you need to manually restore: ### List Backups ```bash -ls -lht ~/.local/share/hexai/prompts/backups/ +ls -lht ~/.local/hexai/data/prompts/backups/ ``` Output: @@ -135,8 +135,8 @@ Output: ### Restore from Backup ```bash # Copy backup to restore -cp ~/.local/share/hexai/prompts/backups/user.jsonl.20260210-193422 \ - ~/.local/share/hexai/prompts/user.jsonl +cp ~/.local/hexai/data/prompts/backups/user.jsonl.20260210-193422 \ + ~/.local/hexai/data/prompts/user.jsonl # Restart MCP client to reload ``` diff --git a/docs/mcp-features-summary.md b/docs/mcp-features-summary.md index 8cfc141..090b616 100644 --- a/docs/mcp-features-summary.md +++ b/docs/mcp-features-summary.md @@ -41,7 +41,7 @@ The hexai-mcp-server is a complete Model Context Protocol implementation with pr ### 5. Storage & Organization - ✅ **JSONL format** - Git-friendly, human-readable - ✅ **Separate files** - `default.jsonl` (built-in), `user.jsonl` (custom) -- ✅ **XDG-compliant** - `~/.local/share/hexai/prompts/` +- ✅ **XDG-compliant** - `~/.local/hexai/data/prompts/` - ✅ **Configurable** - Override via flag, env var, or config file - ✅ **Tag-based categorization** - Filter and organize prompts @@ -123,7 +123,7 @@ hexai-prompt restore 1 ```bash # Edit user.jsonl directly -$EDITOR ~/.local/share/hexai/prompts/user.jsonl +$EDITOR ~/.local/hexai/data/prompts/user.jsonl # Validate after editing hexai-prompt validate @@ -141,7 +141,7 @@ hexai-prompt validate Every write operation (create/update/delete) automatically creates a timestamped backup: ``` -~/.local/share/hexai/prompts/backups/ +~/.local/hexai/data/prompts/backups/ ├── user.jsonl.20260210-190358 ├── user.jsonl.20260210-192145 └── user.jsonl.20260210-193422 @@ -270,7 +270,7 @@ git commit -m "Add team prompt" git push # Team members import -jq -c . team-prompt.json >> ~/.local/share/hexai/prompts/user.jsonl +jq -c . team-prompt.json >> ~/.local/hexai/data/prompts/user.jsonl ``` ## 🔧 Configuration @@ -305,7 +305,7 @@ jq -c . team-prompt.json >> ~/.local/share/hexai/prompts/user.jsonl ### Storage Location -**Default**: `~/.local/share/hexai/prompts/` +**Default**: `~/.local/hexai/data/prompts/` **Override** (priority order): 1. `--prompts-dir /path/to/prompts` (CLI flag) diff --git a/docs/mcp-managing-prompts.md b/docs/mcp-managing-prompts.md index 282564a..675e0c8 100644 --- a/docs/mcp-managing-prompts.md +++ b/docs/mcp-managing-prompts.md @@ -16,9 +16,9 @@ All prompt management is done through the MCP server protocol. Use any MCP clien ## 📍 Prompt Locations -- **Default prompts**: `~/.local/share/hexai/prompts/default.jsonl` (built-in, auto-regenerated) -- **Custom prompts**: `~/.local/share/hexai/prompts/user.jsonl` (your prompts) -- **Backups**: `~/.local/share/hexai/prompts/backups/` (automatic backups) +- **Default prompts**: `~/.local/hexai/data/prompts/default.jsonl` (built-in, auto-regenerated) +- **Custom prompts**: `~/.local/hexai/data/prompts/user.jsonl` (your prompts) +- **Backups**: `~/.local/hexai/data/prompts/backups/` (automatic backups) - **Override directory**: Set `HEXAI_MCP_PROMPTS_DIR` environment variable ## 📝 Method 1: Using MCP Protocol (Recommended) @@ -102,10 +102,10 @@ Use your MCP client (Claude Code, Cursor) to list prompts, or use the MCP protoc ### Edit user.jsonl ```bash # Using your editor -$EDITOR ~/.local/share/hexai/prompts/user.jsonl +$EDITOR ~/.local/hexai/data/prompts/user.jsonl # Or with nano -nano ~/.local/share/hexai/prompts/user.jsonl +nano ~/.local/hexai/data/prompts/user.jsonl ``` ### Prompt Format (JSONL - one line per prompt) @@ -145,7 +145,7 @@ nano ~/.local/share/hexai/prompts/user.jsonl **To add**: Minify with `jq -c` and append: ```bash -jq -c . my-prompt.json >> ~/.local/share/hexai/prompts/user.jsonl +jq -c . my-prompt.json >> ~/.local/hexai/data/prompts/user.jsonl ``` ## 📝 Method 3: Programmatic Access (Go) @@ -159,7 +159,7 @@ import ( ) func main() { - dir := "/home/paul/.local/share/hexai/prompts" + dir := "/home/paul/.local/hexai/data/prompts" store, _ := promptstore.NewJSONLStore(dir) prompt := &promptstore.Prompt{ @@ -205,7 +205,7 @@ Some MCP clients (like Claude Code, Cursor) may cache the prompt list: ### View Automatic Backups ```bash -ls -lht ~/.local/share/hexai/prompts/backups/ +ls -lht ~/.local/hexai/data/prompts/backups/ ``` Output shows timestamped backups (most recent first): @@ -217,14 +217,14 @@ Output shows timestamped backups (most recent first): ### Restore from Backup (Manual) ```bash # Copy backup to restore -cp ~/.local/share/hexai/prompts/backups/user.jsonl.20260210-193422 \ - ~/.local/share/hexai/prompts/user.jsonl +cp ~/.local/hexai/data/prompts/backups/user.jsonl.20260210-193422 \ + ~/.local/hexai/data/prompts/user.jsonl ``` ### Import a Prompt ```bash # From a JSON file -jq -c . imported-prompt.json >> ~/.local/share/hexai/prompts/user.jsonl +jq -c . imported-prompt.json >> ~/.local/hexai/data/prompts/user.jsonl hexai-prompt validate ``` @@ -244,7 +244,7 @@ git push ```bash cd team-prompts/ for f in *.json; do - jq -c . "$f" >> ~/.local/share/hexai/prompts/user.jsonl + jq -c . "$f" >> ~/.local/hexai/data/prompts/user.jsonl done ``` @@ -264,7 +264,7 @@ done **Method 2**: Edit user.jsonl directly ```bash -$EDITOR ~/.local/share/hexai/prompts/user.jsonl +$EDITOR ~/.local/hexai/data/prompts/user.jsonl # Find the line with the prompt name and edit it hexai-prompt validate ``` @@ -276,8 +276,8 @@ store.Update(prompt) // Updates existing prompt by name ### Count Prompts ```bash -wc -l ~/.local/share/hexai/prompts/default.jsonl # Built-in -wc -l ~/.local/share/hexai/prompts/user.jsonl # Custom +wc -l ~/.local/hexai/data/prompts/default.jsonl # Built-in +wc -l ~/.local/hexai/data/prompts/user.jsonl # Custom ``` ## 🛠️ Troubleshooting @@ -285,23 +285,23 @@ wc -l ~/.local/share/hexai/prompts/user.jsonl # Custom ### Invalid JSON ```bash # Check specific file -jq empty ~/.local/share/hexai/prompts/user.jsonl +jq empty ~/.local/hexai/data/prompts/user.jsonl ``` ### Prompt Not Appearing ```bash # Check MCP server logs -tail -f ~/.local/state/hexai/hexai-mcp-server.log +tail -f ~/.local/hexai/state/hexai-mcp-server.log # Verify file exists -cat ~/.local/share/hexai/prompts/user.jsonl | jq . +cat ~/.local/hexai/data/prompts/user.jsonl | jq . ``` ### Duplicate Prompt Names Prompt names must be unique. If you have duplicates: ```bash # List all prompt names -cat ~/.local/share/hexai/prompts/user.jsonl | jq -r .name | sort | uniq -d +cat ~/.local/hexai/data/prompts/user.jsonl | jq -r .name | sort | uniq -d # Fix: Edit user.jsonl and rename or remove duplicates ``` @@ -309,10 +309,10 @@ cat ~/.local/share/hexai/prompts/user.jsonl | jq -r .name | sort | uniq -d ### Reset to Defaults ```bash # Backup first -cp ~/.local/share/hexai/prompts/default.jsonl ~/backup/ +cp ~/.local/hexai/data/prompts/default.jsonl ~/backup/ # Delete and let server recreate -rm ~/.local/share/hexai/prompts/default.jsonl +rm ~/.local/hexai/data/prompts/default.jsonl # Restart MCP server or wait for next request ``` diff --git a/docs/mcp-prompts.md b/docs/mcp-prompts.md index 23ce453..2297281 100644 --- a/docs/mcp-prompts.md +++ b/docs/mcp-prompts.md @@ -150,14 +150,14 @@ Prompts are stored in two files: - `default.jsonl`: Built-in prompts (automatically created) - `user.jsonl`: Your custom prompts -Both files are in: `~/.local/share/hexai/prompts/` (or your configured directory) +Both files are in: `~/.local/hexai/data/prompts/` (or your configured directory) ### Method 1: Manual Editing Edit `user.jsonl` directly: ```bash -cd ~/.local/share/hexai/prompts/ +cd ~/.local/hexai/data/prompts/ nano user.jsonl ``` @@ -211,7 +211,7 @@ prompt = { } # Append to user.jsonl -with open("~/.local/share/hexai/prompts/user.jsonl", "a") as f: +with open("~/.local/hexai/data/prompts/user.jsonl", "a") as f: f.write(json.dumps(prompt) + "\n") ``` @@ -228,7 +228,7 @@ import ( ) func main() { - store, _ := promptstore.NewJSONLStore("~/.local/share/hexai/prompts/") + store, _ := promptstore.NewJSONLStore("~/.local/hexai/data/prompts/") prompt := &promptstore.Prompt{ Name: "security_audit", @@ -407,7 +407,7 @@ Example tags: Store prompts in git for team collaboration: ```bash -cd ~/.local/share/hexai/prompts/ +cd ~/.local/hexai/data/prompts/ git init git add user.jsonl git commit -m "Add custom prompts" diff --git a/docs/mcp-server-complete.md b/docs/mcp-server-complete.md index aa7e043..5d8d7ca 100644 --- a/docs/mcp-server-complete.md +++ b/docs/mcp-server-complete.md @@ -16,7 +16,7 @@ The hexai-mcp-server is a **fully self-contained MCP server** that manages promp - ✅ **Every write operation** creates a timestamped backup - ✅ Backups created **before** changes (can always rollback) - ✅ Keeps last **10 backups** automatically -- ✅ Stored in `~/.local/share/hexai/prompts/backups/` +- ✅ Stored in `~/.local/hexai/data/prompts/backups/` - ✅ **Zero configuration** - works out of the box ### 3. No External Tools Required @@ -151,7 +151,7 @@ Every operation automatically: ### Backup Files ``` -~/.local/share/hexai/prompts/backups/ +~/.local/hexai/data/prompts/backups/ ├── user.jsonl.20260210-193422 ← Most recent ├── user.jsonl.20260210-192145 ├── user.jsonl.20260210-190358 @@ -162,11 +162,11 @@ Every operation automatically: ```bash # List backups -ls -lht ~/.local/share/hexai/prompts/backups/ +ls -lht ~/.local/hexai/data/prompts/backups/ # Restore from backup -cp ~/.local/share/hexai/prompts/backups/user.jsonl.20260210-193422 \ - ~/.local/share/hexai/prompts/user.jsonl +cp ~/.local/hexai/data/prompts/backups/user.jsonl.20260210-193422 \ + ~/.local/hexai/data/prompts/user.jsonl # Restart MCP client ``` @@ -174,7 +174,7 @@ cp ~/.local/share/hexai/prompts/backups/user.jsonl.20260210-193422 \ ## 📁 File Structure ``` -~/.local/share/hexai/prompts/ +~/.local/hexai/data/prompts/ ├── default.jsonl # Built-in prompts (7 prompts) ├── user.jsonl # Your custom prompts └── backups/ # Automatic backups (10 most recent) @@ -234,7 +234,7 @@ cp ~/.local/share/hexai/prompts/backups/user.jsonl.20260210-193422 \ ### Prompts Directory -**Default**: `~/.local/share/hexai/prompts/` +**Default**: `~/.local/hexai/data/prompts/` **Override** (priority order): 1. CLI flag: `--prompts-dir /path/to/prompts` diff --git a/docs/mcp-setup.md b/docs/mcp-setup.md index 4ea3a0b..6f75cb9 100644 --- a/docs/mcp-setup.md +++ b/docs/mcp-setup.md @@ -84,7 +84,7 @@ claude mcp remove hexai-prompts -s user **Server Options:** - `--config`: Path to hexai config file (optional) -- `--log`: Path to log file (default: `~/.local/state/hexai/hexai-mcp-server.log`) +- `--log`: Path to log file (default: `~/.local/hexai/state/hexai-mcp-server.log`) - `--prompts-dir`: Directory for prompt storage (optional) - `--version`: Print version and exit @@ -119,12 +119,12 @@ Any MCP-compatible client can use hexai-mcp-server. The general pattern is: ## Prompts Directory -By default, prompts are stored in `~/.local/share/hexai/prompts/` (XDG_DATA_HOME). You can customize this location using: +By default, prompts are stored in `~/.local/hexai/data/prompts/` (XDG_DATA_HOME). You can customize this location using: 1. **Command-line flag**: `--prompts-dir /path/to/prompts` 2. **Environment variable**: `HEXAI_MCP_PROMPTS_DIR=/path/to/prompts` 3. **Config file**: Add `prompts_dir = "/path/to/prompts"` to `[mcp]` section in `config.toml` -4. **Default**: `$XDG_DATA_HOME/hexai/prompts/` or `~/.local/share/hexai/prompts/` +4. **Default**: `$XDG_DATA_HOME/prompts/` or `~/.local/hexai/data/prompts/` **Precedence order** (highest to lowest): 1. Command-line flag (`--prompts-dir`) @@ -194,7 +194,7 @@ chmod +x ~/go/bin/hexai-mcp-server **Check the log file**: ```bash -tail -f ~/.local/state/hexai/hexai-mcp-server.log +tail -f ~/.local/hexai/state/hexai-mcp-server.log ``` Common issues: @@ -206,19 +206,19 @@ Common issues: 1. Verify prompts directory exists: ```bash - ls -la ~/.local/share/hexai/prompts/ + ls -la ~/.local/hexai/data/prompts/ # Should show default.jsonl and possibly user.jsonl ``` 2. Check default.jsonl has content: ```bash - wc -l ~/.local/share/hexai/prompts/default.jsonl + wc -l ~/.local/hexai/data/prompts/default.jsonl # Should show 7 or more lines ``` 3. Verify JSON format: ```bash - jq -s '.' ~/.local/share/hexai/prompts/default.jsonl + jq -s '.' ~/.local/hexai/data/prompts/default.jsonl # Should parse successfully ``` |
