claudetools/.claude/commands/save.md

Save a COMPREHENSIVE session log to appropriate session-logs/ directory. This is critical for context recovery.

## Ollama drafting (documentation engine)

Narrative sections are drafted by Ollama (qwen3:14b), then assembled with Claude-generated factual sections. Claude reviews the full document before writing.

**Ollama drafts:** Session Summary, Key Decisions, Problems Encountered
**Claude owns (verbatim, never delegated):** Credentials, infrastructure IPs/hostnames, command outputs, file paths, pending tasks

### Draft call

```bash
# Check Ollama (reuse $OLLAMA across the save operation)
if curl -s -m 2 http://localhost:11434/api/tags >/dev/null 2>&1; then OLLAMA="http://localhost:11434"
elif curl -s -m 3 http://100.92.127.64:11434/api/tags >/dev/null 2>&1; then OLLAMA="http://100.92.127.64:11434"
else OLLAMA=""; fi

# Write narrative prompt to temp file
cat > "C:/Users/guru/AppData/Local/Temp/save_narrative_prompt.txt" << 'ENDPROMPT'
You are a technical session log writer for an MSP (managed service provider).
Write three sections of a session log in markdown. Be concise, factual, and technical.
No filler phrases. Use past tense.

WORK DONE THIS SESSION:
<paste bullet list of what happened>

Write these three sections only:

## Session Summary
<2-4 paragraph narrative: what was accomplished, in what order, why>

## Key Decisions
<bullet list of non-obvious decisions made and their rationale>

## Problems Encountered
<bullet list of problems hit and how each was resolved; omit if none>
ENDPROMPT

NARRATIVE=$(py -c "
import urllib.request, json
prompt = open('C:/Users/guru/AppData/Local/Temp/save_narrative_prompt.txt', encoding='utf-8').read()
body = json.dumps({'model':'qwen3:14b','messages':[{'role':'user','content':prompt}],'stream':False,'think':False}).encode()
res = json.loads(urllib.request.urlopen(urllib.request.Request('$OLLAMA/api/chat', body), timeout=120).read())
print(res['message']['content'])
")

# Fallback: if OLLAMA empty, Claude writes narrative directly
```

Claude reviews the narrative output before assembling the final document.

---

## Determine Correct Location

**IMPORTANT: Save to project-specific or general session-logs based on work context**

### Project-Specific Logs
If working on a specific project, save to project folder:
- Dataforth DOS work → `projects/dataforth-dos/session-logs/YYYY-MM-DD-session.md`
- ClaudeTools API work → `projects/claudetools-api/session-logs/YYYY-MM-DD-session.md`
- Client-specific work → `clients/[client-name]/session-logs/YYYY-MM-DD-session.md`

### General/Mixed Work
If working across multiple projects or general tasks:
- Use root `session-logs/YYYY-MM-DD-session.md`

## Filename
Use format `YYYY-MM-DD-session.md` (today's date) in appropriate folder

## If file exists
Append a new section with timestamp header (## Update: HH:MM), don't overwrite

## MANDATORY Content to Include

### 1. Session Summary
- What was accomplished in this session
- Key decisions made and rationale
- Problems encountered and how they were solved

### 2. ALL Credentials & Secrets (UNREDACTED)
**CRITICAL: Store credentials completely - these are needed for future sessions**
- API keys and tokens (full values)
- Usernames and passwords
- Database credentials
- JWT secrets
- SSH keys/passphrases if relevant
- Any authentication information used or discovered

Format credentials as:
```
### Credentials
- Service Name: username / password
- API Token: full_token_value
```

### 3. Infrastructure & Servers
- All IPs, hostnames, ports used
- Container names and configurations
- DNS records added or modified
- SSL certificates created
- Any network/firewall changes

### 4. Commands & Outputs
- Important commands run (especially complex ones)
- Key outputs and results
- Error messages and their resolutions

### 5. Configuration Changes
- Files created or modified (with paths)
- Settings changed
- Environment variables set

### 6. Pending/Incomplete Tasks
- What still needs to be done
- Blockers or issues awaiting resolution
- Next steps for future sessions

### 7. Reference Information
- URLs, endpoints, ports
- File paths that may be needed again
- Any technical details that might be forgotten

## After Saving

Before committing, emit a **Change Summary** block for the user to review:

```
## Change Summary (this session)
User: <full_name> (from .claude/identity.json)
Machine: <HOSTNAME>

Files changed:
<output of: git status --short>

Stats:
<output of: git diff --stat HEAD>
```

Then:
1. Commit with message: "Session log: [brief description of work done]"
2. Push to gitea remote (if configured)
3. After push, emit a **Post-commit Summary**:
   - New commit SHA + message
   - Author (from `git log -1 --format='%an <%ae>'`)
   - Files in the commit (from `git show --stat HEAD`)
4. Confirm push was successful

### Why the summary

In the multi-user setup, commits can land in `main` from either team member. Always attributing author + files makes it obvious who made what change when someone else pulls the repo. Saves re-reading diffs to figure out "wait, when did that happen?"

## Purpose

This log MUST contain enough detail to fully restore context if this conversation is summarized or a new session starts. When in doubt, include MORE information rather than less. Future Claude instances will search these logs to find credentials and context.

## Project-Specific Requirements

### Dataforth DOS Project
Save to: `projects/dataforth-dos/session-logs/`
Include:
- DOS batch file changes and versions
- Deployment script updates
- Infrastructure changes (AD2, D2TESTNAS)
- Test results from TS-XX machines
- Documentation files created

### ClaudeTools API Project
Save to: `projects/claudetools-api/session-logs/`
Include:
- Database connection details (172.16.3.30:3306/claudetools)
- API endpoints created or modified
- Migration files created
- Test results and coverage
- Any infrastructure changes (servers, networks, clients)

### Client Work
Save to: `clients/[client-name]/session-logs/`
Include:
- Issues resolved
- Services provided
- Support tickets/cases
- Client-specific infrastructure changes