joakimp/mempalace-toolkit
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Fix two docs/UX errors found during Mac install (tor-ms22)

Browse Source 
1. 'mempalace init --yes' without a dir argument fails — 'dir' is
   required. The semantics were wrong too: 'mempalace init' is
   per-project (sets up mempalace.yaml + entity detection in a specific
   directory), not a one-time global init. The palace itself is
   created lazily on first write, so neither mempalace-session nor
   mempalace-docs requires any init step.

   Removed the misleading 'One-time palace init' block from README.md,
   ARCHITECTURE.md, and SKILL.md. Added a clarifying note:
   'mempalace init <dir>' is per-project and optional (needed only to
   customize the wing name or entity detection before mempalace-docs).

2. install.sh's 'Skipping <name>: <dest> exists and is not our symlink'
   warning gave no actionable guidance. On the Mac, a leftover
   ~/.local/bin/mempalace-docs (likely from the pre-split cli_utils
   days) was blocking the new install and the user had no easy way
   to know what to do about it.

   Expanded the warning to:
   - Show whether the blocker is a symlink (and what it points at) or
     a real file.
   - Print the exact 'rm && ./install.sh' fix line.
   - Track skipped count separately and flag it in the closing
     summary so a scrolling user doesn't miss it.

   Added matching troubleshooting paragraph to the README 'Install
   mempalace-toolkit' section explaining the skip behaviour and
   pointing at the installer's own message for the fix.

Smoke-tested the new skip-warning code path by temporarily replacing
~/.local/bin/mempalace-docs with a foreign symlink and re-running
install.sh — output is clear, specific, and restores cleanly.
This commit is contained in:
Joakim Persson
2026-04-30 07:32:50 +00:00
parent d69e95d422
commit 72e7019101
4 changed files with 33 additions and 16 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+8 -5
View File
@@ -170,21 +170,24 @@ Ensure `~/.local/bin` is on `$PATH`:
export PATH="$HOME/.local/bin:$PATH"
```
**If `install.sh` reports `Skipping <name> — already exists`:** there's a leftover symlink or file at `~/.local/bin/<name>` from a previous install (e.g. the pre-split `cli_utils` days). The installer prints the exact `rm && ./install.sh` command to fix it — remove the stale entry and re-run. It will never clobber an existing file without the user explicitly removing it first.
### First mine
```bash
# One-time palace init (if not done)
mempalace init --yes
# Mine opencode session history into wing_conversations
# Mine opencode session history into wing_conversations (no init needed)
mempalace-session --dry-run # preview qualifying sessions
mempalace-session # do it (~20 min per 60 sessions)
# Mine a project (docs only)
# Mine a project (docs only). If you want to pre-init the project with a
# custom wing name or entity config, run `mempalace init --yes <dir>` first;
# otherwise `mempalace-docs` derives the wing from the directory name.
mempalace-docs /workspace/my_project --dry-run
mempalace-docs /workspace/my_project
```
> **Note:** mempalace has no one-time global init. The palace itself is created lazily on first write (at `~/.mempalace/palace/`). `mempalace init <dir>` is a *per-project* command that sets up a `mempalace.yaml` + entity list for a specific source directory — optional, not a prerequisite for either wrapper.
### Keeping it fresh (automation)
Manual invocation is fine while you're actively driving the machine, but long-running devboxes benefit from a weekly automated mine. [`contrib/`](contrib/) ships ready-to-install templates: