feat(shell): add interactive cya shell session (CYA-WP-0007)

Implement the full interactive shell REPL with session persistence,
opt-in capped/redacted shell history, State Hub orientation and
explicit slash-command writes, orchestrator/safety wiring, end-session
learning hooks, weakness hints, docs, and tests.

AGENTS.md

@@ -217,3 +217,24 @@ To create a new workplan:
 1. Write the file following the format above
 2. Notify the custodian operator to run `make fix-consistency REPO=can-you-assist`
    (or send a message to the hub agent via `POST /messages/`)
+---
+
+## `cya shell` Command Reference
+
+Interactive shell sessions are an owned repo capability. Use them for manual
+operator assistance, not autonomous command execution.
+
+```bash
+cya shell                         # start a stateful shell session
+cya shell --offline --no-hub      # local smoke without hub HTTP calls
+cya shell --with-history          # opt in to capped, redacted history context
+```
+
+Session artifacts live at `~/.config/cya/sessions/<session-id>.jsonl`.
+Shell history is off by default and remains capped/redacted when enabled.
+
+Slash commands: `/help`, `/explain`, `/hub`, `/hub log "summary"`, `/inbox`,
+`/inbox read <id>`, `/export-session`, `/learn`, `/exit`.
+
+State Hub writes are never automatic. `/hub log` requires interactive
+confirmation; `/inbox read <id>` is the explicit mark-read action.