@b0tts/template-dev-installer 1.0.0

package/cli.mjs

@@ -0,0 +1,129 @@
+#!/usr/bin/env node
+
+// ── template-dev-installer ──────────────────────────────────────────
+// Interactive installer that copies selected template categories into
+// the current working directory.
+//
+// Categories:
+//   1. Skills   — AGENTS.md, README.md, .agents/
+//   2. OpenCode — .opencode/plugins/, opencode.json, settings.json
+//   3. Pi       — .pi/agent/settings.json, extensions/, mcp.json
+//   4. All      — everything above
+// ────────────────────────────────────────────────────────────────────
+
+import { select, confirm } from "@inquirer/prompts";
+import { cpSync, existsSync } from "node:fs";
+import { resolve, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const FILES = resolve(__dirname, "files");
+const CWD = process.cwd();
+
+// ── Category definitions ────────────────────────────────────────────
+// Each category maps to source dirs/files relative to ./files/ and
+// their destination relative to the user's CWD.
+
+const CATEGORIES = {
+  skills: {
+    label: "Skills (AGENTS.md, README.md, .agents/)",
+    items: [
+      { src: "AGENTS.md",              dest: "AGENTS.md" },
+      { src: "README.md",              dest: "README.md" },
+      { src: ".agents",                dest: ".agents" },
+    ],
+  },
+  opencode: {
+    label: "OpenCode (.opencode/plugins, opencode.json, settings.json)",
+    items: [
+      { src: "opencode/plugins",        dest: ".opencode/plugins" },
+      { src: "opencode/opencode.json",  dest: ".opencode/opencode.json" },
+      { src: "opencode/settings.json",  dest: ".opencode/settings.json" },
+    ],
+  },
+  pi: {
+    label: "Pi (.pi/agent/settings.json, extensions/, mcp.json)",
+    items: [
+      { src: "pi/settings.json",        dest: ".pi/agent/settings.json" },
+      { src: "pi/extensions",           dest: ".pi/agent/extensions" },
+      { src: "pi/mcp.json",             dest: ".pi/agent/mcp.json" },
+    ],
+  },
+};
+
+// ── Helpers ─────────────────────────────────────────────────────────
+
+function warnIfExists(destPath) {
+  if (existsSync(destPath)) {
+    console.log(`  ⚠  ${destPath} already exists — will be overwritten.`);
+  }
+}
+
+function copyItem(item) {
+  const src = resolve(FILES, item.src);
+  const dest = resolve(CWD, item.dest);
+  if (!existsSync(src)) {
+    console.log(`  ✘  Source not found: ${item.src}  (skipping)`);
+    return;
+  }
+  warnIfExists(dest);
+  cpSync(src, dest, { recursive: true, force: true });
+  console.log(`  ✓  ${item.dest}`);
+}
+
+function installCategory(name) {
+  const cat = CATEGORIES[name];
+  console.log(`\n── Installing ${cat.label.split(" (")[0]} ──`);
+  for (const item of cat.items) {
+    copyItem(item);
+  }
+}
+
+// ── Main ────────────────────────────────────────────────────────────
+
+async function main() {
+  console.log("━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━");
+  console.log("  Development Template Installer");
+  console.log("━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n");
+
+  const choice = await select({
+    message: "Which template category do you want to install?",
+    choices: [
+      { name: "Skills",        value: "skills" },
+      { name: "OpenCode",      value: "opencode" },
+      { name: "Pi",            value: "pi" },
+      { name: "All",           value: "all" },
+    ],
+  });
+
+  if (choice === "all") {
+    const ok = await confirm({
+      message: `Install everything into ${CWD}? Existing files will be overwritten.`,
+      default: true,
+    });
+    if (!ok) {
+      console.log("Aborted.");
+      process.exit(0);
+    }
+    for (const name of Object.keys(CATEGORIES)) {
+      installCategory(name);
+    }
+  } else {
+    const ok = await confirm({
+      message: `Install "${CATEGORIES[choice].label}" into ${CWD}?`,
+      default: true,
+    });
+    if (!ok) {
+      console.log("Aborted.");
+      process.exit(0);
+    }
+    installCategory(choice);
+  }
+
+  console.log("\n✔  Done.\n");
+}
+
+main().catch((err) => {
+  console.error("Error:", err.message);
+  process.exit(1);
+});

package/files/.agents/skills/_explain-it-v1-disabled/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: explain-it
+description: Beginner-friendly walkthrough of a file, code snippet, or error message — calibrated to the user's level via quick grilling. Use when user says "explain this", "walk me through", "what does this do", "teach me this", "break this down", or pastes an error and asks "what happened".
+disable-model-invocation: true
+---
+
+# Explain It
+
+Walk the user through a file, code snippet, or error message section by section, calibrated to their actual understanding.
+
+## Phase 1: Gather
+
+Determine what's being explained:
+
+- **File in project** → read it in full
+- **Code in chat** → work from the conversation directly
+- **Error message** → work from the pasted text
+
+If the file references other files (imports, configs, schemas), read those too — but only if they're short and directly relevant.
+
+## Phase 2: Calibrate
+
+### Quick check (always)
+
+Ask 2-3 rapid-fire questions to gauge the user's level with the technologies in the file. One question at a time.
+
+**Style:** casual, low-pressure. Frame it as "help me calibrate" not "let me test you."
+
+Example calibration questions:
+- "Have you worked with [technology] before, or is this new?"
+- "Quick gut check — what do you think [concept] does? Even a wrong guess helps me calibrate."
+- "On a scale of 'never seen it' to 'use it daily', where are you with [thing]?"
+
+If a question can be answered from the codebase or conversation history (e.g., they've been working with SQL all session), figure it out yourself instead of asking.
+
+### Grill session (optional)
+
+After the quick check, offer a deeper calibration:
+
+> "Want to do a quick grill session? I'll ask a few more targeted questions to dial in exactly where you're at — takes about a minute and means I won't over-explain stuff you already know."
+
+If yes: interview one question at a time. Probe specific concepts that appear in the file. For each concept, determine if the user genuinely understands it, sort of gets it, or has no clue. Move on once you have a clear picture. Don't pad with unnecessary questions.
+
+If no: proceed with what you know from the quick check.
+
+### Build the level map
+
+Based on all answers, tag each concept/technology in the file:
+- ✅ **Knows it** → correct terminology, skip basics, focus on project-specific usage
+- 🟡 **Sort of knows it** → brief refresh, then connect to the new context
+- ❌ **No idea** → plain English, analogies, tables, build from scratch
+
+If the user says "just explain it" or "skip the questions" → default to beginner and go.
+
+## Phase 3: Explain
+
+Walk through section by section.
+
+### For each section:
+
+1. **Name it** — what this section does, in one plain sentence
+2. **Show the code** — reference the actual lines
+3. **Break it down** using:
+   - **Tables** for structured comparisons (column meanings, permissions, options)
+   - **Analogies** for abstract concepts (badges, whiteboards, snapshots)
+   - **Plain English translations** of technical syntax
+4. **Why it matters** — one line on why this section exists
+
+### For error messages:
+
+1. **TL;DR** — what went wrong in plain English
+2. **The fix** — what to do about it
+3. **Why it happened** — the underlying cause
+4. **Prevention** — what to watch for next time
+
+### After all sections:
+
+End with a **connection diagram** — ASCII art showing how all the pieces relate. This is the "how it all comes together" moment.
+
+## Rules
+
+- **One section at a time** for large files (>50 lines). Smaller files can be explained in one pass.
+- **Match the user's level** — don't explain what `SELECT` means if they said they know SQL.
+- **Use their project's context** — reference their actual names, data, and use cases.
+- **Pause for questions** — after every 2-3 sections, check in: "Questions on that, or keep going?"
+- **No setup overhead** — conversational only. Don't create tracking files or lesson plans unless asked.

package/files/.agents/skills/close/SKILL.md

@@ -0,0 +1,112 @@
+---
+name: close
+description: Close out a coding session by reviewing chat memory and proposing memory-file updates, new skills, skill improvements, helpful tips, and a session log. Use when the user says '/close', 'close this session', 'wrap up', 'end session', or wants to close out the current conversation.
+---
+
+# /close
+
+## Quick start
+
+When the user invokes `/close`:
+
+1. Present a multi-select menu of the 5 closing steps.
+2. Run selected steps in fixed order: Memory → Skills → Improvements → Tips → Log.
+3. For proposal branches (1–4), use the ranked proposal loop.
+4. Write the session log last if selected.
+
+## Menu
+
+Present this multi-select menu:
+
+```
+What do you want to close with? (multi-select)
+[ ] 1. Update memory files    — propose AGENTS.md edits from this session
+[ ] 2. Propose new skills     — spot reusable work worth a skill
+[ ] 3. Improve skills used    — QoL fixes for skills touched this session
+[ ] 4. Helpful Tips           — suggest time-saving systems and QoL ideas
+[ ] 5. Write session log      — log to b0ttsagent/sessionlogs/
+[ ] 6. All
+```
+
+If nothing selected, exit with "Nothing selected, closing."
+
+## Branch 1: Update memory files
+
+- Read the session for memory-worthy items: corrections, additions, deprecations, decisions.
+- Threshold: durable + actionable + not already captured elsewhere.
+- Ranking: corrections > high-impact additions > elegance/insight > deprecations > decisions.
+- Target files:
+  - Default: `./AGENTS.md`, `~/.pi/agent/AGENTS.md`
+  - Auto-discover: `CONTEXT.md`, `CLAUDE.md`, `.planning/*.md`, `References/NavGuides/*.md`, `docs/adr/*.md`, root `README.md`
+- Use the proposal loop.
+- On approval, apply the edit directly to the target file.
+
+## Branch 2: Propose new skills
+
+- Identify reusable workflows or QoL improvements from the session.
+- Ranking: reusability + QoL (highest), clear trigger, scope focus, creative/novel.
+- Check existing skill front matter to avoid exact duplicates. Similar skills are allowed with a quick context note.
+- Use the proposal loop.
+- On approval, write a complete `SKILL.md` to `~/.pi/agent/skills/<name>/SKILL.md`.
+- If the name collides with an existing skill, block and propose an alternative.
+
+## Branch 3: Improve skills used
+
+- Scope: skills actually invoked during this session. Exclude `/close` itself.
+- Ranking: observed painpoint ≈ QoL improvement > outdated info > clarification.
+- Use the proposal loop.
+- On approval, apply the edit directly to the target skill file.
+
+## Branch 4: Helpful Tips
+
+- Identify session-derived ideas for time-saving systems, automation, organization, tooling, or workflow improvements.
+- Ranking: quick win (high time/money savings, low effort) > repeated manual work > error reduction / cognitive load > organization / discoverability > nice-to-have. Within each tier, prefer ideas with long-term viability.
+- Let the model decide what qualifies; avoid hard-coded heuristics.
+- Tips may overlap conceptually with branches 1–3. Deduplicate against items already proposed in this run so the user doesn't see the same suggestion twice.
+- Use the proposal loop.
+- Present each tip with: category tag, title, observation from the session, recommendation, and estimated impact.
+- On approval, acknowledge the tip and continue. Do not generate implementation code; the user can ask for that separately after closing.
+
+## Proposal loop (branches 1–4)
+
+1. Present the top 3 items with full detail (target, rationale, proposed change).
+2. User multi-selects which to approve. Apply approved edits immediately (for branches 1–3); for Helpful Tips, acknowledge and continue.
+3. Present the next 3 items as one-line summaries.
+4. User can expand some, skip the batch, or exit the loop.
+5. Loop ends on explicit exit.
+6. When the pool is empty, acknowledge it and ask an open prompt: "No more items in this pool. Anything I missed, or shall we move on?"
+7. Declined/unselected items are gone forever.
+
+## Branch 5: Write session log
+
+- Run last.
+- Generate 3 filename ideas in lowercase kebab-case; recommend one.
+- **Pause for user confirmation** — user may choose a different name, adjust the recommended name, or skip entirely.
+- Once confirmed, write to `b0ttsagent/sessionlogs/<MM-DD-YYYY>/<HHMM>_<name>.md`
+- Use this template:
+
+```markdown
+# <selected_name>
+
+**Date:** MM-DD-YYYY  
+**Time:** HH:MM  
+
+## What happened
+- ...
+
+## Skills used
+- ...
+
+## Closing outcomes
+- ...
+
+## Open / next
+- ...
+```
+
+## Edge cases
+
+- **Empty branch**: ask the user whether to skip or write a minimal log.
+- **New skill name collision**: block and propose an alternative name.
+- **Missing target file**: ask the user whether to recreate the file with the proposed content.
+- **Mid-run abort**: no special handling; immediate apply preserves already-approved work.

package/files/.agents/skills/closev2/REFERENCE.md

@@ -0,0 +1,194 @@
+# closev2 — Reference
+
+## Scratchpad file format
+
+Every scratchpad file uses this structure:
+
+```markdown
+# Scratchpad — Branch <N>: <branch-name>
+**Session:** <session-name>
+**Date:** MM-DD-YYYY HH:MM
+
+## Categories identified
+- <category-1>
+- <category-2>
+- ...
+
+## Extraction
+
+### <category-1>
+- <item>
+- <item>
+...
+
+### <category-2>
+- (none identified)
+...
+
+## Gleaning Pass
+
+### <category-1>
+- *Re-checked <range>: <result>* — either new items found or justification for none
+...
+
+### <category-2>
+- *Re-checked <range>: no additional items qualify because <reason>*
+...
+```
+
+Each item under a category uses a bullet with this structure:
+```
+- Brief, specific description of the item. Context: what happened in the session. Reason: why it matters.
+```
+
+Empty categories are **never deleted** — they stay as `(none identified)` with a gleaning entry explaining why.
+
+---
+
+## Self-taxonomy instructions
+
+Before extracting, the model identifies 3–7 categories that fit the branch and the session. Categories should be:
+
+- **Specific** — not "misc" or "things"
+- **Session-aware** — named after what actually happened, not generic placeholders
+- **Actionable** — each category should produce items the branch can use
+
+### By branch
+
+**Branch 1 — Memory files:** Look for changes the session made to the project's understanding. Good categories: architectural-decisions, tooling-choices, path-conventions, deprecations, new-facts, corrections, project-state-changes. The scan covers: what was decided, what was learned, what changed, what's now outdated.
+
+**Target files (where edits apply):** Default — `./AGENTS.md`, `~/.pi/agent/AGENTS.md`. Auto-discover — `CONTEXT.md`, `CLAUDE.md`, `.planning/*.md`, `References/NavGuides/*.md`, `docs/adr/*.md`, root `README.md`.
+
+**Branch 2 — New skills:** Look for workflows the model executed that follow a reusable shape. Good categories: repeated-patterns, multi-step-workflows, automation-worthy, config-templates. The scan covers: tasks done more than once, tasks with a clear trigger and output, things a future session would benefit from having templated.
+
+**Branch 3 — Improve skills:** Look at skills actually invoked this session (excluding `/close` and `/closev2`). Good categories: missing-coverage, friction-points, outdated-references, poor-triggering, missing-edge-cases. The scan covers: times the model struggled with a skill, times the skill didn't cover a case, times the skill's instructions were wrong or incomplete.
+
+**Branch 4 — Tips:** Look for meta-level improvements to workflow, tooling, or organization. Good categories: repeated-manual-work, automation-opportunity, organizational-gap, tooling-idea, cognitive-load-reduction. The scan covers: inefficiencies, things the user did manually, things that could be faster or clearer.
+
+---
+
+## Priority ranking rules
+
+The model maps its self-defined categories onto these fixed tiers for each branch, then ranks items accordingly.
+
+### Branch 1 — Memory files
+1. **Corrections** — things that were wrong and got fixed
+2. **High-impact additions** — new information that would cause friction if forgotten
+3. **Deprecations** — things now outdated that should be removed
+4. **Decisions** — choices made with reasoning
+5. **Elegance/insight** — quality-of-life improvements, clarity
+
+### Branch 2 — New skills
+1. **Reusability + QoL** — most frequently reusable, highest time savings
+2. **Clear trigger** — well-defined "when to invoke"
+3. **Scope focus** — narrow enough to be reliable
+4. **Creative/novel** — interesting but less tested
+
+### Branch 3 — Improve skills
+1. **Observed painpoint ≈ QoL improvement** — things that caused friction this session
+2. **Outdated information** — references that are wrong
+3. **Clarification** — ambiguous instructions that slowed the model down
+
+### Branch 4 — Tips
+1. **Quick win** — high time/money savings, low effort
+2. **Repeated manual work** — things done by hand that could be automated
+3. **Error reduction / cognitive load** — things that reduce mistakes or mental overhead
+4. **Organization / discoverability** — things that make info easier to find
+5. **Nice-to-have** — long-term ideas, lower urgency
+
+Within each tier, prefer items with long-term viability.
+
+---
+
+## Gleaning pass — per-category forcing question
+
+The `## Gleaning Pass` section must have one entry per category from `## Categories identified`. For each category, the model re-reads the conversation and answers:
+
+> **Is there an item in the conversation that fits this category but is NOT in the extraction above?**
+> - If yes: add it to the extraction section and note it in the gleaning entry.
+> - If no: briefly state where in the conversation you looked (message range or topic) and why nothing qualified. Blanket "re-checked, nothing found" is insufficient.
+
+Example gleaning entry:
+```
+### architectural-decisions
+- Re-checked messages 1-45 (the full skill redesign discussion): no additional architectural decisions missed. The extraction covers per-branch scratchpad, self-taxonomy, file layout, and ranking approach.
+```
+
+Example with missed items:
+```
+### friction-points
+- Re-checked the skill invocation at message 12: missed a friction point. The model had to ask clarifying questions about the skill's scope because the trigger description was too broad. Added to extraction above.
+```
+
+---
+
+## Triple-check protocol
+
+This ONLY activates when every self-defined category in the Gleaning Pass section has no new items found.
+
+1. Re-read the ENTIRE conversation from the first message to the last.
+2. Ignore your categories entirely.
+3. List EVERY factual claim, action taken, file edited, tool used, and question asked in the session.
+4. For each item in that list, ask: does this belong in the current branch? If yes, add it to the extraction and the gleaning pass. If no, state why not.
+5. If after this pass the extraction is still empty: write a paragraph explaining why this specific conversation genuinely had nothing relevant to this branch, referencing specific conversation events.
+
+---
+
+## Proposal loop — full flow
+
+The proposal loop runs after all scratchpads are written and verified. It is the SAME loop for all branches (1–4). Every batch of 3 items is presented with full detail — no condensed one-line summaries, no expand step.
+
+### Per-batch format
+
+Begin each batch with a **batch preview** line listing each item's target and tags:
+
+> `AGENTS.md rule (high-impact / low-effort) · docs/adr/ index (medium-impact / medium-effort) · workflow idea (medium-impact / low-effort)`
+
+Tags show impact and effort: `high-impact`, `medium-impact`, `low-impact`; `high-effort`, `medium-effort`, `low-effort`. If effort is irrelevant (e.g., a mindset shift), omit the effort tag.
+
+Present 3 items at a time. Each item format:
+
+```
+**<N>. <target-or-domain>: <one-line-action-summary>** `<category-tag>`
+Impact: <one-line statement of what changes if applied — consequences of doing vs not doing>
+How: <mechanism — file path, exact content, target location, how it works>
+Why: <what happened in the session that surfaced this, and why it matters now>
+Risk: <edge case or watch-out, if any; omit if none>
+```
+
+Fields in order: Headline → Impact → How → Why → Risk (optional).
+
+**File-based proposals:** target is the primary file path, secondary files go in How. **Non-file proposals (Tips):** target is a domain label (e.g., `Workflow`, `Tooling`, `Organization`, `Mindset`), and the third field is `How to act on this:` instead of `How:`.
+
+After presenting the items, end with a line listing the user's available actions:
+
+> *"Select numbers to approve (numbers, range, or 'all'), or say 'skip' / 'none' to skip this batch, or 'exit' / 'done' to end the loop."*
+
+Apply approved edits immediately for Branches 1–3; for Branch 4 (Tips), just acknowledge.
+
+Mention the scratchpad path after the first batch only: *"Full extraction at `<path>`."*
+
+### Loop end
+
+Loop ends when the user explicitly exits or the pool is exhausted. When the pool is exhausted, ask: *"No more items in this pool. Anything I missed, or shall we move on?"* If user suggests something, add it to the pool and resume the loop. Otherwise, move to the next branch.
+
+Declined or skipped items are gone forever — do not re-propose them.
+
+---
+
+## File layout
+
+```
+b0ttsagent/
+├── scratchpads/
+│   └── <MM-DD-YYYY>/
+│       ├── <HHMM>_<session-name>_scratchpad-memory.md
+│       ├── <HHMM>_<session-name>_scratchpad-skills.md
+│       ├── <HHMM>_<session-name>_scratchpad-improvements.md
+│       └── <HHMM>_<session-name>_scratchpad-tips.md
+└── sessionlogs/
+    └── <MM-DD-YYYY>/
+        └── <HHMM>_<session-name>.md
+```
+
+`<HHMM>` is the time the close session started, in 24-hour format. All scratchpad files and the session log share the same timestamp and session name.

package/files/.agents/skills/closev2/SKILL.md

@@ -0,0 +1,84 @@
+---
+name: closev2
+description: Close out a coding session with deep context extraction, memory-file updates, skill proposals, skill improvements, tips, and a session log. Use when user says '/close', 'close this session', 'wrap up', 'end session', or wants to close out the current conversation. Forces exhaustive reflection via per-branch scratchpads before any proposals are made.
+---
+
+# /closev2
+
+## Quick start
+
+1. Present menu → user selects branches
+2. Propose 3 session names → user picks one
+3. Write all selected branch scratchpads upfront, verify them, then run each proposal loop in branch order (Memory → Skills → Improvements → Tips)
+4. Run Branch 5 (session log) last
+5. If nothing selected, exit with "Nothing selected, closing."
+
+## Step 1 — Menu
+
+Present this menu, exactly as shown:
+
+    What do you want to close with? (multi-select)
+    [ ] 1. Update memory files    — propose AGENTS.md edits from this session
+    [ ] 2. Propose new skills     — spot reusable work worth a skill
+    [ ] 3. Improve skills used    — QoL fixes for skills touched this session
+    [ ] 4. Helpful Tips           — suggest time-saving systems and QoL ideas
+    [ ] 5. Write session log      — log to b0ttsagent/sessionlogs/
+    [ ] 6. All
+
+    I'll do a deep scan of our conversation before proposing anything.
+
+## Step 2 — Session name
+
+Propose 3 filename ideas in lowercase kebab-case. Recommend one. Wait for user confirmation — they may choose a different name, adjust the recommended one, or skip (use a timestamp-only name). This name is used for all scratchpad files and the session log.
+
+## Step 3 — Branch processing
+
+Run selected branches in fixed order: Memory → Skills → Improvements → Tips.
+
+### 3a — Write all scratchpads
+
+Write all selected branch scratchpads upfront, in branch order. For each: use the scratchpad format and self-taxonomy instructions in [REFERENCE.md](REFERENCE.md). Write to `b0ttsagent/scratchpads/<MM-DD-YYYY>/<HHMM>_<session-name>_scratchpad-<branch>.md`.
+
+Each file MUST include a `## Gleaning Pass` section at the bottom. See REFERENCE.md for the per-category forcing question.
+
+**Triple-check:** if every self-defined category in the Gleaning Pass has no new items, run the triple-check protocol in REFERENCE.md.
+
+### 3b — Verify all scratchpads
+
+1. Read each scratchpad file you just wrote.
+2. Confirm: each file exists and has a `## Gleaning Pass` section.
+3. For any that fail: re-write that scratchpad. If it fails a second time: offer the user (i) retry with a different path, (ii) inline extraction into a visible message, or (iii) skip this branch. Do not skip silently.
+
+### 3c — Proposal loops
+
+For each selected branch, in order: read the branch's scratchpad, rank items using the fixed priority rules (see REFERENCE.md), then run the proposal loop:
+
+1. Present a batch preview line, then 3 items with full detail: headline (target + action), Impact, How, Why, and optional Risk. Format is defined in REFERENCE.md.
+2. Mention where the full extraction lives: *"Full extraction at `<scratchpad-path>`."* (once, after the first batch).
+3. User multi-selects which to approve.
+4. For Branches 1–3: apply approved edits immediately. For Branch 4 (Tips): acknowledge and continue.
+5. Present next 3 items with the same full-detail format. Every batch gets full detail — no one-line summaries.
+6. User can approve (multi-select), skip the batch, or exit.
+7. Loop ends on explicit exit.
+8. If pool is empty: *"No more items. Anything I missed, or shall we move on?"*
+9. Declined/unselected items are gone forever.
+
+### 3d — Tips dedup
+
+Branch 4 (Tips) only: before presenting, check whether an item was already proposed in any earlier branch (accepted or declined). If yes, skip it.
+
+## Step 4 — Session log
+
+Run last, even if Branches 1–4 were not selected.
+
+Use the session name from Step 2. Write to `b0ttsagent/sessionlogs/<MM-DD-YYYY>/<HHMM>_<session-name>.md` with:
+- `# <session-name>` header, Date, Time
+- `## What happened`, `## Skills used`, `## Closing outcomes`, `## Open / next`
+
+## Edge cases
+
+- **Empty branch**: ask to skip or write minimal log.
+- **Skill name collision**: block, propose alternative.
+- **Missing target file**: ask to recreate with proposed content.
+- **Mid-run abort**: no special handling; approved work is preserved.
+- **File write failure**: follow Step 3b soft escape — retry once, offer alternatives, never skip silently.

package/files/.agents/skills/create-nav-guide/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: create-nav-guide
+description: Generate a reference document (nav guide) from the current conversation. Use when user says "doc this", "write this up", "make a reference", "create a nav guide", "document what we just did", or similar.
+---
+
+# Create Nav Guide
+
+## What this skill does
+
+Reads the current conversation and produces a markdown nav guide in `b0ttsagent/NavGuides/`. The guide is written for two audiences: the user as a personal reference, and future AI assistants who need to understand the setup before suggesting changes or additions.
+
+## Workflow
+
+1. **Extract** key information from the conversation — only what's actually present, don't invent.
+2. **Generate front matter** — produce `name`, `topics`, and `description` from the conversation content. Use the naming convention matching the filename (e.g. `MinecraftModsGuide`).
+3. **Write overview table** — key properties as a markdown table. Adapt fields to the domain (ports, locations, credentials, versions, config values — whatever is relevant). Don't force Docker-specific fields onto non-Docker setups.
+4. **Write key systems** — one section per major subsystem that has its own commands or configuration. For each: what it does, how to operate it, current state.
+5. **Write gotchas** — brief blockquotes (`>`) for anything non-obvious that caused problems during setup.
+6. **Avoid duplication** — scan related nav guides in `b0ttsagent/NavGuides/` for overlapping topics. Don't repeat information already covered there. Reference them if needed.
+7. **Present** — show the generated guide to the user for confirmation before writing the file.
+
+## What to leave out
+
+- Step-by-step setup instructions — current state only
+- Speculative future features
+- Things that worked without incident
+
+## Format rules
+
+- Markdown only, with YAML front matter
+- Tables for config values and key properties
+- Bash code blocks for all commands
+- Gotchas as `>` blockquotes inline with the relevant section
+- No preamble, no closing remarks
+- Section headers should match the actual systems — don't use generic headers like "Configuration" if a more specific name fits (e.g. "Backups", "Chunky", "RCON")
+
+## Output
+
+Write to `b0ttsagent/NavGuides/<name>.md` after user confirms.