summaryrefslogtreecommitdiff
path: root/docs
diff options
context:
space:
mode:
authorPaul Buetow <paul@buetow.org>2026-02-11 20:53:45 +0200
committerPaul Buetow <paul@buetow.org>2026-02-11 20:53:45 +0200
commita82d0b061a02fd395de293353386d0b16cbe6b18 (patch)
tree55ac689596267b43d5dbcdc608cfc23472c2faf8 /docs
parent8312a19b4e1f9849aae9912433824b19e03a8daf (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.md8
-rw-r--r--docs/mcp-features-summary.md10
-rw-r--r--docs/mcp-managing-prompts.md42
-rw-r--r--docs/mcp-prompts.md10
-rw-r--r--docs/mcp-server-complete.md14
-rw-r--r--docs/mcp-setup.md14
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
```