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