Add PA knowledge base design and handoff docs

- Design doc: two-KB architecture (shared + PA-private)
- Lazy-load with session caching
- Minified JSON format for all state files
- Hybrid learning (explicit + implicit with confirmation)
- Handoff doc for next session implementation

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

docs/plans/2025-12-28-pa-knowledge-base-design.md

@@ -0,0 +1,135 @@
+# PA Knowledge Base Design
+
+**Status:** Approved
+**Date:** 2025-12-28
+**Author:** PA + User brainstorm session
+
+## Problem
+
+PA makes assumptions about infrastructure facts (e.g., assumed k3s instead of k0s) when it could check a local knowledge base first. As PA expands to handle non-tech tasks (target: 50%+), it needs a lightweight fact store that doesn't bloat the context window.
+
+## Design Decisions
+
+### Architecture
+
+Two knowledge bases:
+
+| KB | Location | Writers | Readers | Content |
+|----|----------|---------|---------|---------|
+| Shared | `~/.claude/state/kb.json` | PA only | PA, k8s-*, sysadmin, all agents | Infrastructure facts |
+| PA-private | `~/.claude/state/personal-assistant/kb.json` | PA only | PA only | Personal, non-tech facts |
+
+### Format
+
+**Minified JSON** - All state files use minified format (no prettification). ~10% token savings; no human readers.
+
+**Categorized with terse keys:**
+
+```json
+{"infra":{"cluster":"k0s","nodes":3,"arch":"arm64"},"svc":{"gitops":"argocd","mon":"prometheus"},"net":{"domain":"local","ingress":"traefik"},"hw":{"pi5":2,"pi3":1}}
+```
+
+**Initial categories:**
+
+| Key | Purpose | Example facts |
+|-----|---------|---------------|
+| `infra` | Cluster/platform | cluster type, node count, architecture |
+| `svc` | Services/tools | gitops, monitoring, alerting |
+| `net` | Network | domain, ingress controller, DNS |
+| `hw` | Hardware | device models, RAM, storage |
+
+### Loading Strategy
+
+**Lazy-load** - PA reads KB only when needed, not at session start.
+
+**Session caching** - Once a category is loaded, cache in context for the session.
+
+**Query priority** - For factual questions: check KB before web search.
+
+### Learning Behavior
+
+**Hybrid approach:**
+
+1. **Explicit:** `/pa --fact "cluster is k0s"` or `/pa --fact infra.cluster=k0s`
+2. **Implicit:** When PA is corrected on a fact, it asks: "Want me to add this to the KB?"
+
+User confirms before any write.
+
+### Access Control
+
+- PA is the sole writer to both KBs
+- Domain agents (k8s-*, sysadmin, etc.) read shared KB only
+- Domain agents cannot request additions; they are passive consumers
+- Domain agents have static context in their instruction files; KB is for dynamic facts
+
+## File Format Specification
+
+### Shared KB (`~/.claude/state/kb.json`)
+
+```json
+{"infra":{},"svc":{},"net":{},"hw":{}}
+```
+
+Values should be primitives (string, number, boolean) or flat arrays. Avoid nested objects beyond category level.
+
+### PA-private KB (`~/.claude/state/personal-assistant/kb.json`)
+
+Same format. Categories TBD based on future non-tech use cases. Initial empty structure:
+
+```json
+{}
+```
+
+## Implementation Changes
+
+### 1. Create KB files
+
+- `~/.claude/state/kb.json` with initial categories
+- `~/.claude/state/personal-assistant/kb.json` empty
+
+### 2. Update PA agent instructions
+
+Add to `~/.claude/agents/personal-assistant.md`:
+- KB file locations and access patterns
+- Lazy-load behavior description
+- Learning behavior (explicit + implicit)
+- New `/pa --fact` command
+
+### 3. Update `/pa` command
+
+Add to `~/.claude/commands/pa.md`:
+- `--fact "<fact>"` - Add fact to appropriate KB
+- `--fact <category>.<key>=<value>` - Structured addition
+- `--list-facts` - Show KB contents
+- `--list-facts <category>` - Show specific category
+
+### 4. Update CLAUDE.md
+
+Add KB files to shared state table.
+
+### 5. Document in state-schemas.md
+
+Add KB schema documentation.
+
+### 6. Minify existing state files
+
+Convert all `~/.claude/state/*.json` to minified format.
+
+## Future Considerations
+
+- **fc-012:** Session caching mechanism (in progress via this design)
+- **fc-013:** Vector database for semantic search (deferred)
+
+## Out of Scope
+
+- Agent-to-agent KB requests (agents are passive consumers)
+- Automatic fact expiration/staleness detection
+- KB versioning or history
+
+## Testing
+
+After implementation:
+1. PA should check KB before making infrastructure assumptions
+2. `/pa --fact` should add facts correctly
+3. Correction detection should offer to save facts
+4. Domain agents should be able to read shared KB

docs/plans/2025-12-28-pa-knowledge-base-handoff.md

@@ -0,0 +1,103 @@
+# Handoff: PA Knowledge Base Implementation
+
+**Date:** 2025-12-28
+**Design Doc:** `~/.claude/docs/plans/2025-12-28-pa-knowledge-base-design.md`
+**Status:** Ready for implementation
+
+## Context
+
+User and PA brainstormed a knowledge base system so PA can check local facts before making assumptions or querying the web. Design is approved.
+
+## Implementation Tasks
+
+### 1. Create KB files
+
+```bash
+# Shared KB - infrastructure facts
+echo '{"infra":{"cluster":"k0s","nodes":3,"arch":"arm64"},"svc":{"gitops":"argocd","mon":"prometheus","alerts":"alertmanager"},"net":{},"hw":{"pi5_8gb":2,"pi3_1gb":1}}' > ~/.claude/state/kb.json
+
+# PA-private KB - empty for now
+echo '{}' > ~/.claude/state/personal-assistant/kb.json
+```
+
+### 2. Minify all existing state JSON files
+
+Convert these to single-line minified format:
+- `~/.claude/state/system-instructions.json`
+- `~/.claude/state/future-considerations.json`
+- `~/.claude/state/model-policy.json`
+- `~/.claude/state/autonomy-levels.json`
+- `~/.claude/state/personal-assistant-preferences.json`
+- `~/.claude/state/personal-assistant/general-instructions.json`
+- `~/.claude/state/personal-assistant/session-context.json`
+- `~/.claude/state/sysadmin/session-autonomy.json`
+
+Use: `jq -c . file.json > tmp && mv tmp file.json`
+
+### 3. Update PA agent (`~/.claude/agents/personal-assistant.md`)
+
+Add section after "Memory Management":
+
+```markdown
+### Knowledge Base
+
+**Files:**
+- Shared: `~/.claude/state/kb.json` (read/write)
+- Private: `~/.claude/state/personal-assistant/kb.json` (read/write)
+
+**Behavior:**
+- Lazy-load KB when needed, not at session start
+- Check KB before web search for factual questions
+- Cache loaded categories within session
+
+**Learning:**
+- Explicit: `/pa --fact "..."` adds to KB
+- Implicit: When corrected, offer to save fact with user confirmation
+```
+
+### 4. Update `/pa` command (`~/.claude/commands/pa.md`)
+
+Add to flags section:
+
+```markdown
+### Knowledge Base
+
+```
+/pa --fact "<description>"          # Add fact (PA determines category)
+/pa --fact <cat>.<key>=<value>      # Add structured fact
+/pa --list-facts                    # Show all KB contents
+/pa --list-facts <category>         # Show specific category
+```
+```
+
+### 5. Update CLAUDE.md
+
+Add to "Shared State Files" table:
+
+```markdown
+| `~/.claude/state/kb.json` | Shared knowledge base | personal-assistant |
+```
+
+### 6. Update state-schemas.md
+
+Add KB schema documentation.
+
+### 7. Update future-considerations.json
+
+Change fc-012 status from "designing" to "implementing" or "resolved".
+
+## Verification
+
+After implementation:
+
+1. Test lazy-load: `/pa what cluster type do we run?` should read KB and answer "k0s"
+2. Test fact addition: `/pa --fact net.dns=pihole` should update KB
+3. Test implicit learning: Correct PA on a fact, confirm it offers to save
+4. Verify domain agents can read: Spawn k8s-diagnostician, have it reference KB
+
+## Notes
+
+- All state JSON files are now minified (no prettification)
+- PA is sole writer to both KBs
+- Domain agents are passive consumers (read-only, no requests)
+- Keep values as primitives or flat arrays; avoid deep nesting