docs(claude-config): establish Claude/Claude-Code research + config home

- Dedicated directory for research on current/future Claude & Claude Code
  usage, the decisions that follow, and config/implementation work
- .claude/context.md (auto-injected here), README, research/INDEX.md,
  decisions/DECISIONS.md, config/ convention
- Moved local-ai-coding-stack-research.md into research/
- Live homelab config (settings.json, /opt/appdata/docker/.claude hooks+skills)
  stays authoritative in place; memory not migrated

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01X9iCzmxK2zbb8H1Ld3f8AN

claude-config/.claude/context.md

@@ -0,0 +1,67 @@
+# Claude & Claude Code — Research & Config Home — Context
+
+## What this project does
+The dedicated home for everything about **how we use Claude and Claude Code to do work** —
+research on the current setup and where we want to take it, the decisions that come out of that
+research, and the actual config/implementation work when we adopt something. If we research a
+tool (e.g. jcode/OpenCode, a local model, LifeOS, voice input) and decide to use it, the setup
+happens here too.
+
+## Directory layout
+- `README.md` — front door: purpose + how the directory is organized.
+- `research/` — research findings, one file per topic. `research/INDEX.md` is the catalog
+  (topic, status, open decisions). Add new findings as new files and index them.
+- `decisions/DECISIONS.md` — the log linking research → decision → implementation. Every
+  adopt/reject/defer call lands here with a date and a pointer to the research that drove it.
+- `config/` — where implementation/setup artifacts land when a decision moves to action
+  (scripts, compose snippets, wiring notes). `config/README.md` explains the convention.
+
+## Key files
+- `research/local-ai-coding-stack-research.md` — seed brief: inference engine (Ollama vs vLLM
+  on the RTX 2060 Super / 8 GB ceiling), coding harnesses (jcode/OpenCode/Aider/Cline/Goose),
+  LifeOS context layer, macOS→LMDE skill porting, voice input. Surface-level, in progress.
+- `research/INDEX.md` — research catalog + open decisions.
+- `decisions/DECISIONS.md` — decision log.
+
+## Live config this project reasons about (authoritative — edit in place, NOT stored here)
+- `/home/administrator/.claude/settings.json` — global settings, hook + plugin registration.
+- `/opt/appdata/docker/.claude/hooks/` — all hooks (globally referenced by settings.json).
+- `/opt/appdata/docker/.claude/skills/` — homelab-skills plugin (skills live here).
+- Memory dirs (do NOT migrate — homelab-wide, shared): this session reads
+  `/home/administrator/.claude/projects/-home-administrator-Desktop-claude/memory/`;
+  `/opt/appdata/docker/.claude/...` is the other primary memory root.
+
+## Patterns to follow
+- Research is additive: new topic = new file in `research/`, then a row in `research/INDEX.md`.
+  Re-verify version/repo/Linux claims before acting — this space moves fast (noted in the brief).
+- Every decision gets a dated entry in `decisions/DECISIONS.md` pointing back to its research.
+- Config work touching live infra edits the authoritative files in place; back up hooks first
+  (`cp hook.sh hook.sh.bak.YYYYMMDD`), validate Python with
+  `python3 -c "import ast; ast.parse(open('file').read())"` before saving.
+- Keep the design-principle memories in force: evolution mechanism on anything new, training-data
+  question answered, Jenkins/Hermes fit evaluated for any automation.
+
+## Known issues / gotchas
+- Naming overlap: the PARENT dir `/home/administrator/Desktop/claude/.claude/context.md` also
+  declares `project_name: claude-config` (the older Sat/Sun config-AUDIT workflow). That context
+  is a subset of this broader home. Parent-dir sessions still load the parent context; sessions
+  started in THIS subdir load this one. Not yet unified — noted deliberately.
+- This dir currently lives inside the parent homelab git repo as an (until committed) untracked
+  folder — git ops here act on the parent repo. Revisit if a standalone repo is ever wanted.
+- The custom SessionStart hook derives the project name from the cwd basename ("claude-config").
+
+## What NOT to break
+- Do not move/relocate live hooks or skills out of `/opt/appdata/docker/.claude/` — settings.json
+  references them by absolute path; moving them breaks running automation.
+- Do not migrate the memory directories — they are homelab-wide, not specific to this project.
+
+## Current state
+2026-09-08: Directory established as the Claude/Claude-Code research + config home. Moved the
+existing `local-ai-coding-stack-research.md` into `research/`, created the catalog, decision log,
+and config convention. Next: fold in findings from the earlier Claude-chatbot research session
+and decide the goal framing (cost / independence / fully-local) that the local-stack brief hinges
+on before going deeper on jcode/OpenCode/local-model choices.
+
+## Update instructions
+Update this file during every session debrief that touches this project — keep "Current state",
+"Directory layout", and "Known issues" current after every session.

claude-config/README.md

@@ -0,0 +1,33 @@
+# claude-config
+
+The home for everything about **how we use Claude and Claude Code to do work** — research on
+the current setup and where we want to take it, the decisions that come out of that research, and
+the actual config/implementation work when we adopt something.
+
+If we research a tool or workflow and decide to use it, the setup happens here too. Example: the
+current research covers jcode/OpenCode as open-source alternatives to Claude Code — if we decide
+to adopt one, its install + Claude integration is done from this directory.
+
+## How this is organized
+
+| Path | Holds |
+|---|---|
+| `research/` | Research findings — one file per topic. Start at `research/INDEX.md`. |
+| `decisions/DECISIONS.md` | Every adopt / reject / defer call, dated, pointing back to the research that drove it. |
+| `config/` | Implementation artifacts once a decision moves to action (scripts, wiring notes). |
+| `.claude/context.md` | Auto-injected into every session started here, so a fresh session knows the mission. |
+
+## Working conventions
+
+- **New research** → new file in `research/`, then add a row to `research/INDEX.md`. Findings
+  move fast (local models, jcode, LifeOS) — re-verify versions/repos/Linux support before acting.
+- **New decision** → dated entry in `decisions/DECISIONS.md` linking the research and the outcome.
+- **Implementation** → artifacts in `config/`; but live homelab config (`~/.claude/settings.json`
+  and the hooks/skills under `/opt/appdata/docker/.claude/`) is edited **in place** — this
+  directory tracks the work and the reasoning, it is not a relocation of the running config.
+
+## What lives elsewhere (on purpose)
+
+- **Live Claude Code config** — `~/.claude/settings.json`, hooks + skills under
+  `/opt/appdata/docker/.claude/`. Authoritative there; we edit in place.
+- **Memory** — the homelab-wide memory directories; not migrated here.

claude-config/config/README.md

@@ -0,0 +1,25 @@
+# config/
+
+Implementation and setup artifacts land here when a decision in
+[../decisions/DECISIONS.md](../decisions/DECISIONS.md) moves from "adopt" to actually being done —
+install scripts, compose snippets, wiring notes, env templates for the tool being set up
+(e.g. jcode/OpenCode install + Claude integration, a local model gateway, a LifeOS port).
+
+## Convention
+- One subdirectory per thing being set up (e.g. `config/opencode/`, `config/local-model-gateway/`).
+- Keep a short `NOTES.md` in each explaining what it wires and how to verify it works.
+
+## Important — live config is edited in place, not stored here
+The running Claude Code config is authoritative at its real locations and must be edited there,
+because `~/.claude/settings.json` references hooks/skills by absolute path:
+- `/home/administrator/.claude/settings.json` — global settings, hook + plugin registration.
+- `/opt/appdata/docker/.claude/hooks/` — hooks.
+- `/opt/appdata/docker/.claude/skills/` — homelab-skills plugin.
+
+Back up before modifying (`cp hook.sh hook.sh.bak.YYYYMMDD`) and validate Python
+(`python3 -c "import ast; ast.parse(open('file').read())"`) before saving. This directory holds
+the *setup artifacts and reasoning*, not a relocated copy of the live config.
+
+## Secrets
+No secrets in this directory. Follow the homelab rule: secrets via the secrets-proxy / Vault
+references, never written into files or the terminal.

claude-config/decisions/DECISIONS.md

@@ -0,0 +1,28 @@
+# Decision Log
+
+Every adopt / reject / defer call about how we use Claude / Claude Code. Newest at top. Each
+entry links back to the research that drove it, so the reasoning survives.
+
+## Format
+```
+## YYYY-MM-DD — <short decision title>
+- **Decision:** adopt / reject / defer — <what>
+- **Why:** <one or two lines>
+- **Research:** <link to research/ file(s)>
+- **Implementation:** <link to config/ artifacts, or "n/a" / "pending">
+- **Revisit when:** <trigger that would reopen this>
+```
+
+---
+
+## 2026-09-08 — Establish claude-config as the research + config home
+- **Decision:** adopt — this directory is where Claude/Claude-Code research, decisions, and
+  config/implementation work now live.
+- **Why:** research (local-ai-coding-stack brief, jcode/OpenCode, etc.) had no dedicated home;
+  findings were scattered.
+- **Research:** [../research/INDEX.md](../research/INDEX.md)
+- **Implementation:** directory structure + `.claude/context.md` + README created this session.
+- **Revisit when:** a standalone git repo is wanted, or the parent-dir "claude-config" audit
+  context should be unified with this one.
+
+<!-- Next decisions go above this line, newest first. -->

claude-config/research/INDEX.md

@@ -0,0 +1,29 @@
+# Research Index
+
+Catalog of research on how we use Claude / Claude Code and where we want to take it. One row per
+topic. Add a row whenever a new research file lands here. Findings in this space move fast —
+re-verify versions, repos, and Linux support before acting on anything.
+
+| Topic | File | Status | Key open decision |
+|---|---|---|---|
+| Local AI coding stack (inference engine, coding harness, LifeOS, voice, skill porting) | [local-ai-coding-stack-research.md](local-ai-coding-stack-research.md) | Surface-level, in progress | **Goal framing first:** cost vs. independence vs. fully-local — everything downstream (engine, harness, hybrid) follows from this. |
+
+## Cross-cutting open decisions
+Pulled up from the individual briefs so they don't get buried:
+
+1. **The goal** — cost / independence / fully-local. Governs every other choice in the local
+   stack. (from local-ai-coding-stack-research.md §0)
+2. **8 GB VRAM ceiling** — RTX 2060 Super caps a fully-local setup at ~7–8B @ Q4. Which coding
+   models actually fit *with* agentic context, and how reliable is their tool-calling through a
+   harness? (§1, §2)
+3. **Daily-driver harness** — likely OpenCode for stability; jcode only if its swarm/multi-agent
+   feature earns it. Confirm canonical jcode repo/language before investing. (§3)
+4. **LifeOS** — pin current version, re-check real Linux status per component (docs overstate it),
+   confirm whether LifeOS↔harness pairing needs adapter work. (§4, §5)
+5. **Voice input** — local Whisper dictation vs. reviving LifeOS VoiceServer (needs macOS→LMDE
+   port). (§6)
+
+## To fold in
+- Findings from the earlier Claude-chatbot research session that prompted creating this directory
+  (the reason `local-ai-coding-stack-research.md` exists). Bring those notes in as their own file(s)
+  and index them here.

claude-config/research/local-ai-coding-stack-research.md

@@ -0,0 +1,227 @@
+# Local AI Coding Stack — Research Brief
+
+**Status:** surface-level, in progress. This document exists to seed a future Claude Code
+session so the research can continue without re-deriving what's already known.
+
+**Machine:** LMDE 7 (kernel 6.12.96), Linux home lab. GPU: **RTX 2060 Super, 8 GB VRAM
+(Turing, compute capability SM 7.5)**. Docker container server on the same network.
+
+---
+
+## 0. The strategic framing (read this first)
+
+Three separate threads got tangled together during research. They solve different problems
+and should be decided independently:
+
+1. **Inference engine** — what runs the model weights (Ollama, vLLM, llama.cpp, LM Studio).
+2. **Coding harness** — the agent that reads the repo, writes edits, runs commands
+   (Claude Code, jcode, OpenCode, Aider, Cline, Goose).
+3. **Context / intent layer** — LifeOS. A *different kind* of harness (life/work operations,
+   not code editing).
+
+**Critical constraint that none of the harness choices touch:** the 8 GB VRAM ceiling. On a
+2060 Super, a fully local setup is limited to a ~7–8B model at 4-bit quant. That governs
+output quality regardless of which engine or harness sits on top.
+
+**Decision to make before going deeper — what is actually being optimized for?**
+- (a) **Cost** — get off Anthropic's per-token pricing.
+- (b) **Independence** — not be locked to one vendor's models.
+- (c) **Fully local / $0** — no cloud calls at all.
+
+These point to different answers. (a) and (b) are well served by any model-agnostic harness
++ a cheap API. (c) runs headfirst into the 8 GB ceiling and a real quality drop.
+
+---
+
+## 1. Inference engine: Ollama vs vLLM
+
+### Correction to the original premise
+Local Ollama is **still free** (MIT, unlimited on your own hardware). The paid tiers are
+**Ollama Cloud** (Free / $20 Pro / $100 Max) — a separate hosted-inference product. Pulling
+models with `ollama pull` and running them locally costs nothing and prompts no sign-in. The
+"Ollama went paid" premise was mistaken.
+
+### vLLM on the 2060 Super — verdict: not worth it on this card
+- vLLM's real advantage is **throughput under concurrency** (PagedAttention, continuous
+  batching). For a single-user coding assistant (one request at a time) that advantage is
+  largely wasted.
+- **Turing (SM 7.5) does not support Marlin kernels** (need Ampere+) or **FP8**. It *can* run
+  AWQ / GPTQ / INT8 / GGUF / bitsandbytes, but on slower fallback kernels — so even the raw
+  speed edge is blunted. INT4/W4A16 officially wants compute > 8.0 (Ampere+).
+- On tight 8 GB VRAM, **Ollama (llama.cpp/GGUF) is more graceful** — better at fitting models
+  and offloading overflow to system RAM. vLLM tends to pre-grab a large VRAM block and is
+  fussier when things don't fit.
+
+**Recommendation:** stay on Ollama for this GPU. Revisit vLLM only after a 12–16 GB Ampere+
+upgrade, where Marlin kicks in and the larger models vLLM is built for actually fit.
+
+### Open questions
+- [ ] Which specific 7–8B coding models fit comfortably in 8 GB at Q4 *with* enough context
+      for agentic work (Claude Code / jcode are context-heavy)? Candidates to benchmark:
+      Qwen-Coder family, DeepSeek-Coder family, others current as of research date.
+- [ ] Realistic context-window ceiling at Q4 on 8 GB before RAM offload kills throughput.
+
+---
+
+## 2. Wiring a local model into Claude Code
+
+Claude Code can point at a local model — it just needs an endpoint that speaks the right API.
+
+- Set `ANTHROPIC_BASE_URL` to the local endpoint and `ANTHROPIC_AUTH_TOKEN` to any string
+  (leave `ANTHROPIC_API_KEY` empty so it doesn't fall back to Anthropic auth).
+- **LM Studio (0.4.1+)** exposes a native Anthropic `/v1/messages` endpoint → point Claude
+  Code straight at it.
+- **vLLM** has an official Claude Code integration; serve a tool-calling model with
+  `--enable-auto-tool-choice` and the right `--tool-call-parser`.
+- **OpenAI-only endpoints (incl. Ollama's `/v1`)** need a translation shim — **LiteLLM** is
+  the standard Anthropic-Messages-to-anything gateway.
+
+**Reality check:** the 7–8B models that fit on 8 GB often stumble on Claude Code's multi-step
+agent loop (heavy context + strong tool-calling required). Great for autocomplete, boilerplate,
+offline Q&A; not a drop-in replacement for Claude in the agent seat.
+
+### Open questions
+- [ ] Test tool-calling reliability of the shortlisted local models through the harness.
+- [ ] Decide: local model for *cheap/offline* subtasks, paid API for the *agent driver*? (hybrid)
+
+---
+
+## 3. Coding harness: jcode vs the field
+
+**jcode is a harness, not a model.** Bring any OpenAI-compatible model; it supplies the agent
+loop (repo-aware edits, command execution). Switching to it does **not** provide free
+intelligence — the 8 GB model-quality problem is unchanged.
+
+### What's genuinely distinctive
+- **Extreme RAM efficiency.** Its own benchmarks: ~27.8 MB (local embedding off) for one
+  session vs ~386 MB for Claude Code; the gap widens at scale (10 sessions ≈ 117 MB vs
+  ≈ 2.3 GB). Fast time-to-first-frame.
+- **Multi-agent / swarm features.** Multiple agents in one repo coordinated by a server:
+  edit notifications, agent-to-agent messaging, auto-conflict handling.
+
+### Maturity warning
+Very early and chaotic. Version ~0.81.3; only ~16 Homebrew installs in a year; multiple repos
+all named "jcode" (forks/mirrors — canonical source unclear); even the implementation language
+is described inconsistently (Zig vs Rust). Early-adopter territory.
+
+### More mature model-agnostic alternatives (same "bring any model" benefit)
+- **OpenCode** — most direct terminal-native Claude Code replacement, 75+ providers,
+  client/server (can run server on a remote box).
+- **Aider** — Git-native terminal pair-programmer.
+- **Cline** — strongest VS Code-native agent (Plan/Act mode, MCP marketplace).
+- **Goose** — extensible agent, any backend.
+- **OpenHands** — most-starred; browser UI, SDK, heavier.
+
+### Open questions
+- [ ] Confirm the canonical jcode repo and its actual language/build before investing.
+- [ ] Do you actually need the swarm/multi-session feature? If not, OpenCode is the safer daily
+      driver with the same independence benefit.
+
+---
+
+## 4. LifeOS (Daniel Miessler — also created Fabric)
+
+**Name/lineage:** `danielmiessler/LifeOS`, formerly **PAI (Personal AI Infrastructure)**,
+renamed ~v6.x mid-2026. Author is **Daniel Miessler** (not "Meisler").
+
+**It composes with jcode — it does not replace it.** LifeOS is described as a "Universal AI
+Harness" but of a *different kind*: intent engineering built around a **TELOS** format
+(capturing what you're trying to accomplish) and "current state → ideal state." Its skills are
+life/work operations (calendar, mail, vuln management, security market intel, system
+diagnostics) — **not code editing**. So:
+- **LifeOS = context / intent layer.**
+- **jcode (or Claude Code) = code-execution layer.**
+Using LifeOS *as* a replacement for jcode would leave you with no coding agent.
+
+**Fabric relationship:** Fabric = *what* to ask AI (prompt patterns). LifeOS = *how* your
+assistant operates (memory, skills, routing, context). Complementary; many users fold Fabric
+patterns into LifeOS skills.
+
+**Coupling — better than feared:** LifeOS is **harness-agnostic by design**. Core is TypeScript
++ Bash on universal primitives (hooks, skills, context files, agentic routing). Built/tested on
+Claude Code (most-tested path) but not locked to it; installer detects your harness and *merges*
+settings rather than overwriting. Tested install path needs **Claude Code + bun**.
+
+**Maturity warnings (take seriously):**
+- Linux support has been **documented better than it actually is**. Example: the v3.0
+  VoiceServer had hard macOS dependencies with no Linux fallback, *after* a merged PR (#288)
+  had already added Linux equivalents — that work was **lost in the v3.0 restructuring** while
+  `PLATFORM.md` still listed Linux as "fully supported."
+- Recurring issues: install scripts reporting false success, health checks passing on broken
+  binaries, a Windows install leaving ~17 failing hook files referencing missing directories.
+- Still needs a model behind it → **not** a free-local path.
+
+### Open questions
+- [ ] Pin the current LifeOS version and re-check real Linux status per component (docs lie here).
+- [ ] Confirm whether the LifeOS ↔ jcode pairing needs adapter work, since LifeOS grew up on
+      Claude Code specifically.
+
+---
+
+## 5. Porting the macOS-only skills to LMDE
+
+**Do this first, before writing any port:** check merged-PR history. Linux fixes may already
+exist and have been dropped in a restructuring. **PR #288 is the key reference** — it carried
+the VoiceServer Linux fixes that later vanished.
+
+### The four recurring macOS chokepoints and their Linux equivalents
+| Concern | macOS (as shipped) | Linux equivalent |
+|---|---|---|
+| Audio playback | `afplay` | `mpg123` or `mpv` |
+| Notifications | `osascript` (Notification Center) | `notify-send` (libnotify) |
+| Service management | `launchctl`, `~/Library/LaunchAgents/`, `~/Library/Logs/` | **systemd user service** |
+| System diagnostics | Vitals (macOS perf APIs) | **genuine rewrite** against Linux tooling |
+
+- Audio / notifications / service management are mostly clean substitutions.
+- **Vitals** is a real rewrite, not a substitution — different system APIs entirely.
+- The **systemd user service** piece should suit this box well, given prior systemd
+  socket-activation work here.
+
+### Open questions
+- [ ] Inventory every skill that touches those four concerns; classify each as
+      "substitution" vs "rewrite."
+- [ ] Recover PR #288's approach and re-apply it to the current architecture.
+
+---
+
+## 6. Voice input for Claude Code
+
+Not native — Claude Code is a terminal tool with no built-in voice mode. Two routes:
+
+1. **OS-level dictation (simpler).** Speech-to-text into the terminal so speaking types text.
+   Local, private options on Linux built on **Whisper** (e.g. whisper.cpp-based dictation
+   tools). Covers the "talk instead of type" half.
+2. **LifeOS VoiceServer (fuller).** Purpose-built voice component — but it's the same one with
+   the macOS dependencies above. On LMDE: swap `afplay` → `mpg123`/`mpv`,
+   `osascript` → `notify-send`, `launchctl` → systemd user service. Conveniently the same port
+   already on the skills list.
+
+### Open questions
+- [ ] Pick a local Whisper dictation tool and test latency/accuracy on this hardware.
+- [ ] Decide whether VoiceServer is worth reviving vs. plain OS dictation for the actual need.
+
+---
+
+## 7. Consolidated next steps
+
+1. **Decide the goal** (cost / independence / fully-local) — everything else follows.
+2. Benchmark 2–3 candidate 7–8B coding models on the 2060 Super at Q4 (fit + context + tool
+   calling).
+3. Stand up one hybrid path: Ollama (or LM Studio) locally + a harness, wired into Claude Code
+   via `ANTHROPIC_BASE_URL` (+ LiteLLM if OpenAI-format).
+4. Pick a *daily-driver* harness — likely OpenCode for stability, jcode only if the swarm
+   feature earns it.
+5. Re-verify LifeOS current Linux state; recover PR #288; port the substitution-class skills.
+6. Choose a voice route and prototype it.
+
+## 8. Sources to revisit
+- vLLM quantization hardware support: https://docs.vllm.ai/en/latest/features/quantization/
+- vLLM Claude Code integration: https://docs.vllm.ai/en/stable/serving/integrations/claude_code/
+- LM Studio + Claude Code: https://lmstudio.ai/blog/claudecode
+- jcode (verify canonical repo): https://github.com/jrish11/jcode and https://github.com/1jehuang/jcode
+- LifeOS: https://github.com/danielmiessler/LifeOS
+- LifeOS VoiceServer Linux issue: https://github.com/danielmiessler/LifeOS/issues/685
+- PAI 6.x / LifeOS announcement: https://danielmiessler.com/blog/announcing-pai-5-life-operating-system
+
+> All findings above are as of the research date and move fast (jcode and LifeOS especially).
+> Re-verify versions, repo status, and Linux support before acting.