From 72e70191011601c9b94012c45b90bb223236b2a6 Mon Sep 17 00:00:00 2001 From: Joakim Persson Date: Thu, 30 Apr 2026 07:32:50 +0000 Subject: [PATCH] Fix two docs/UX errors found during Mac install (tor-ms22) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 ' is per-project and optional (needed only to customize the wing name or entity detection before mempalace-docs). 2. install.sh's 'Skipping : 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. --- ARCHITECTURE.md | 10 +++++----- README.md | 13 ++++++++----- SKILL.md | 10 +++++----- install.sh | 16 +++++++++++++++- 4 files changed, 33 insertions(+), 16 deletions(-) diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md index af7bc0b..e80872c 100644 --- a/ARCHITECTURE.md +++ b/ARCHITECTURE.md @@ -147,14 +147,14 @@ cd ~/mempalace-toolkit # 3. Ensure ~/.local/bin is on PATH (installer warns if not) export PATH="$HOME/.local/bin:$PATH" -# 4. Initialize palace if needed (one-time, platform-wide) -mempalace init --yes - -# 5. Mine opencode history into the palace +# 4. Mine opencode history into the palace +# (No global init step needed — the palace is created on first write. +# `mempalace init ` is per-project, not global, and is optional.) mempalace-session --dry-run # preview scope mempalace-session # do it for real (~20 min for ~60 sessions) -# 6. Mine project docs (per project) +# 5. Mine project docs (per project — run `mempalace init --yes ` +# first if you want to customize the wing name or entity detection) mempalace-docs /workspace/my_project --dry-run mempalace-docs /workspace/my_project diff --git a/README.md b/README.md index 7d9b0ff..c86ecee 100644 --- a/README.md +++ b/README.md @@ -170,21 +170,24 @@ Ensure `~/.local/bin` is on `$PATH`: export PATH="$HOME/.local/bin:$PATH" ``` +**If `install.sh` reports `Skipping — already exists`:** there's a leftover symlink or file at `~/.local/bin/` 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 ` 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 ` 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: diff --git a/SKILL.md b/SKILL.md index 6aa4f0f..c9686b6 100644 --- a/SKILL.md +++ b/SKILL.md @@ -46,14 +46,14 @@ cd ~/mempalace-toolkit # 3. Verify ~/.local/bin is on PATH which mempalace-session mempalace-docs -# 4. Initialize palace (one-time, platform-wide) -mempalace init --yes - -# 5. Mine opencode session history into wing_conversations +# 4. Mine opencode session history into wing_conversations +# (No global init needed — the palace is created lazily on first write. +# `mempalace init ` is per-project and optional.) mempalace-session --dry-run # preview: which sessions qualify? mempalace-session # do it (~20 min per 60 sessions) -# 6. Mine project docs per project (docs only — no source code) +# 5. Mine project docs per project (docs only — no source code) +# Optional: `mempalace init --yes ` first to customize wing/entities mempalace-docs /workspace/my_project --dry-run mempalace-docs /workspace/my_project diff --git a/install.sh b/install.sh index 91b4aca..02edb43 100755 --- a/install.sh +++ b/install.sh @@ -76,6 +76,7 @@ install_bin() { mkdir -p "$BIN_DEST" note "Symlinking bin/ executables into $BIN_DEST" local count=0 + local skipped=0 for src in "$BIN_SRC"/*; do [[ -x "$src" && -f "$src" ]] || continue local name; name=$(basename "$src") @@ -86,7 +87,17 @@ install_bin() { count=$((count+1)) continue else - warn "Skipping $name: $dest exists and is not our symlink" + # Tell the user exactly what's in the way and how to fix it. + local what="real file" + if [[ -L "$dest" ]]; then + local current_target + current_target=$(readlink "$dest") + what="symlink → $current_target" + fi + warn "Skipping $name — $dest already exists ($what)" + printf ' If stale (e.g. an old cli_utils install), remove and re-run:\n' + printf ' rm %q && %q/install.sh\n' "$dest" "$SCRIPT_DIR" + skipped=$((skipped+1)) continue fi fi @@ -96,6 +107,9 @@ install_bin() { done echo ok "Installed $count executable(s)" + if (( skipped > 0 )); then + warn "$skipped executable(s) skipped — see notes above" + fi } install_skill() {