claudetools/.claude/commands/save.md

Save a comprehensive session log to the appropriate `session-logs/` directory, then sync the repo.

`/save` and `/sync` share `bash .claude/scripts/sync.sh` as the canonical driver for git operations. The only difference: `/save` writes a session log first, then calls sync. `/sync` calls sync directly (no log).

---

## Phase 1 — Generate the narrative

Claude writes all sections directly. Be concise, factual, technical. No filler phrases. Past tense. No emojis.

| Author | Sections |
|---|---|
| Claude | All sections |

### Narrative sections (Claude writes directly)

**Session Summary** — 3-5 paragraphs: what was accomplished, in what order, why.

**Key Decisions** — bullet list of non-obvious decisions and their rationale.

**Problems Encountered** — bullet list of problems hit and how each was resolved. Omit section if none.

---

## Phase 2 — Write to disk

### Location

| Work scope | Path |
|---|---|
| Single project | `projects/<project>/session-logs/YYYY-MM-DD-session.md` |
| Client | `clients/<slug>/session-logs/YYYY-MM-DD-session.md` |
| Multi-project / general | `session-logs/YYYY-MM-DD-session.md` |

### Filename + append behavior

- Filename: `YYYY-MM-DD-session.md` (today's local date)
- If file exists, **append** a `## Update: HH:MM PT — <topic>` section. Do not overwrite.
- If two users worked on the same date, namespace: `YYYY-MM-DD-<user>-<topic>.md` (e.g. `2026-05-01-howard-syncro-billing-batch.md`)

### Required sections (in order)

1. **User block** — generate it deterministically; do NOT hand-write or infer it. Run:
   ```bash
   bash .claude/scripts/whoami-block.sh
   ```
   Paste its output verbatim as this section. The script reads `.claude/identity.json` (+ `users.json` for role) — the only authoritative attribution sources. Never derive the user from the hostname, the `# userEmail` context hint, or memory. If the script emits a `[WARNING]` about a stale machine/hostname mismatch, stop and fix `identity.json` before saving.
2. **Session Summary** (Ollama)
3. **Key Decisions** (Ollama)
4. **Problems Encountered** (Ollama)
5. **Configuration Changes** — files modified / created / deleted (with paths)
6. **Credentials & Secrets** — UNREDACTED if newly discovered or created. Vault paths if vaulted. Never half-redact a value future-Claude might need.
7. **Infrastructure & Servers** — IPs, hostnames, ports, tenant IDs, container names, DNS, certs
8. **Commands & Outputs** — important one-liners, key outputs, error messages with resolution
9. **Pending / Incomplete Tasks** — what's left, blockers, next steps
10. **Reference Information** — URLs, endpoints, commit SHAs, ticket IDs, routine IDs, file paths

When in doubt, include MORE detail — future sessions search these logs to recover context.

---

## Phase 3 — Wiki Refresh (before sync)

Keep the worked-on wiki article current so it ships in the **same commit** as the session log. This runs before sync. **Refresh only** — it never re-synthesizes narrative (that is `/wiki-compile --full`, run on demand).

1. Derive the slug from the session-log path written in Phase 2:
   - `clients/<slug>/session-logs/...` → client `<slug>`
   - `projects/<project>/session-logs/...` → project article slug (e.g. `guru-rmm`, `guru-connect`)
   - Root `session-logs/...` → **skip this phase entirely** (no single article is implied)

2. **Article exists** (`wiki/clients/<slug>.md` or `wiki/projects/<slug>.md`) → apply the surgical refresh from `/wiki-compile` Phase 4 "Refresh Mode":
   - Frontmatter: set `last_compiled` (today) and `compiled_by` (`<MACHINE>/claude-main`); append the new session-log path to `sources:` (dedupe).
   - **Clients only:** refresh "Hours remaining" and the "Active Work" ticket list from live Syncro (read-only GET; customer id from the article frontmatter). Softfail if Syncro is unreachable — still bump `last_compiled` + `sources`.
   - **Never** touch Patterns, History, or Summary — those require `--full` or human review.

3. **No article yet** → do not auto-seed here (seeding is a full Ollama synthesis, too heavy for every save). Emit:
   ```
   [INFO] No wiki article for '<slug>' yet. Run /wiki-compile client:<slug> to seed it.
   ```

**Softfail:** a wiki-refresh failure must NEVER block the save. Log it and continue to sync. The refreshed article + `wiki/index.md` are picked up by `sync.sh`'s `git add -A` and committed alongside the session log.

---

## Phase 4 — Sync

```bash
bash .claude/scripts/sync.sh
```

`sync.sh` handles: reconcile this machine's `git config user.name/email` to `.claude/identity.json` (so commit authorship can't drift), stage all changes with `git add -A` (after purging garbled Windows path-as-filename cruft), auto-commit, fetch + rebase, push, then the same flow for the vault repo, then surface cross-user `## Note for <user>` blocks.

After sync, emit a **Post-commit Summary**:

```
## Post-commit Summary
Commit:  <sha>  <subject>
Author:  <name> <<email>>
Push:    <old>..<new>  main -> main  (origin)
File:    <session log path>  (+N lines, appended/created)

Wiki updates (if any): <count> articles updated (clients/projects/systems/patterns)
```

---


## Cross-user note handling (CRITICAL)

If `sync.sh` surfaces a `## Note for <user>` or `## Message for <user>` block from an incoming session log, display it **prominently at the top of the response, before the sync summary**:

```
============================================================
MESSAGE FROM <author> (<date>)
============================================================
<full note content>
============================================================
```

Explicitly address each action item or question before moving on.