docs(cli): sync README + AGENTS.md, add cli/CHANGELOG.md, clear stale e2e refs

v0.3 feature commits didn't update the docs alongside; this commit
syncs them and introduces a CLI-local changelog so v0.3+ release
notes stop crowding the project root file.

cli/CHANGELOG.md (new):
- Subsystem-local pattern, mirroring mcp-server/CHANGELOG.md. CLI
  versions independently from server / frontend cadence; reduces
  merge-conflict surface on the shared root file.
- Scope: Added + SDK additions only. v0.3-internal dev churn
  (--top-k → --limit, kb clear-contents → kb empty, link --context
  introduce-then-drop, internal Go type-name leaks) never reached a
  shipped release so it doesn't belong in Changed / Fixed sections.
  mcp-server's v1.0.0 changelog is Added-only for the same reason.
- v0.0–v0.2 history stays in the project root CHANGELOG.md;
  cross-referenced from the top of cli/CHANGELOG.md.

Stale --help / quickstart examples fixed in cli/cmd/root.go,
cli/README.md, and cli/AGENTS.md — all three showed the dropped bare
`weknora search "<q>" --kb=...` form; updated to `search chunks ...`.

AGENTS.md updates:
- Verb canon table gained edit / empty / download / pin / unpin /
  add / remove.
- `auth` subtree description gained `refresh` and the transparent
  401-retry transport (replacing the now-inverted "deferred to v0.3"
  sentence).
- `search` and `session` subtree paragraphs added; top-level
  verb list gained `context` and `session`.

cli/README.md top-level command list gained `session`; `search`
short retitled to the parent description ("Search across chunks,
knowledge bases, documents, or sessions") since search is now a
pure dispatcher.

Pre-existing stale e2e refs swept up while syncing:
- cli/acceptance/doc.go listed e2e/ under "Future v0.2+:" — moved
  into the present-tense Sub-packages block.
- envelope_test.go preamble "Deferred to v0.2 e2e" rephrased to
  "Deferred to the e2e harness" so it isn't pinned to a past version.

Not changed (out of scope, flagged for future PRs):
- envelope_test.go "Implemented count: 16" vs the actual 14 named
  entries — could be a different counting rule; verify with PR-8
  author before editing.
- envelope_test.go context_use deferred-cases narrative is loose
  (context_use.success IS golden-pinned today) but rewriting needs
  careful re-derivation of which error scenarios are still deferred.
- cli/README.md:50 "once v0.2 ships" — v0.2-PR-original wording;
  not load-bearing once a release tag exists.

No project-root CHANGELOG.md change in this commit.

cli/AGENTS.md

@@ -98,18 +98,35 @@ The command tree follows `<noun> <verb>` (gh style). Verbs are:
 | `list` | Multi-resource read | `kb list` |
 | `view` | Single-resource read | `kb view <id>` |
 | `create` | Create resource | `kb create --name X` |
-| `delete` | Destructive remove | `kb delete <id> -y` |
+| `edit` | Partial update (only sent fields change) | `kb edit <id> --description X` |
+| `delete` | Destructive remove (KB itself) | `kb delete <id> -y` |
+| `empty` | Bulk-delete contents, preserve container | `kb empty <id> -y` |
 | `upload` | Bulk write content | `doc upload <file>` |
+| `download` | Stream resource to disk | `doc download <id> -O file` |
+| `pin` / `unpin` | Toggle "pinned" state (idempotent) | `kb pin <id>` |
 | `use` | Switch active selection | `context use <name>` |
+| `add` / `remove` | Manage local config entries | `context add staging --host ...` |
 
-`auth` subtree: `login` / `logout` / `list` / `status`. Mirrors gh's
-`auth login / logout / status / switch / list`-style surface; weknora uses
-`context use` instead of `auth switch` because contexts carry host + tenant
-on top of credentials. Token refresh is deferred to v0.3 (will land as
-transparent 401 retry in the SDK plus an explicit `auth refresh` command).
+`auth` subtree: `login` / `logout` / `list` / `status` / `refresh`. Mirrors
+gh's `auth login / logout / status / switch / list`-style surface; weknora
+uses `context use` instead of `auth switch` because contexts carry host +
+tenant on top of credentials. `auth refresh` exchanges the stored refresh
+token for a new access + refresh pair (OAuth refresh-token grant); it
+errors with `input.invalid_argument` on API-key contexts which have no
+refresh semantic. Transparent 401 → refresh → retry is wired into the
+SDK transport (`cli/internal/cmdutil/authretry.go`) with singleflight
+de-dup, so most callers never need to invoke `auth refresh` explicitly.
+
+`search` subtree: verb-noun (gh `search code/repos/issues/...` shape) —
+`search chunks "<q>" --kb X` for hybrid retrieval, `search kb "<q>"` /
+`search docs "<q>" --kb X` / `search sessions "<q>"` for client-side
+substring filtering on the listing endpoints.
+
+`session` subtree: `list` / `view` / `delete` for chat session
+management. Sessions are the durable wrapper around `chat` invocations.
 
 Top-level RAG / connectivity verbs: `chat`, `search`, `api`, `link`,
-`auth`, `doctor`, `version`.
+`auth`, `context`, `session`, `doctor`, `version`.
 
 `doctor` is a deliberate divergence from gh / lark (neither ships a
 health-check command); the precedent is `flutter doctor` / `brew doctor`.
@@ -211,7 +228,7 @@ release will introduce a `precondition.*` namespace (server returns HTTP 412
 with a typed remediation body before opening the SSE / streaming response):
 
 - `weknora chat` when no chat model is configured for the active tenant
-- `weknora search` when no retriever / vector store is configured
+- `weknora search chunks` when no retriever / vector store is configured
 - `weknora doc upload` when no storage engine is selected for the KB
 
 Workaround until then: if a chat / search / upload call times out without

cli/CHANGELOG.md

@@ -0,0 +1,63 @@
+# Changelog — `weknora` CLI
+
+All notable changes to the `weknora` CLI (the binary under `cli/` in this
+repository) will be documented in this file.
+
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
+and the CLI follows [Semantic Versioning](https://semver.org/) independently
+of the WeKnora server / frontend release cadence.
+
+Earlier history (v0.0 through v0.2) is recorded in the project root
+[CHANGELOG.md](../CHANGELOG.md) under the entries that introduced the CLI.
+
+## [Unreleased]
+
+### v0.3 — extended management surface and a `session` subtree
+
+#### Added
+- `context add` / `context list` / `context remove` — first-class CRUD over
+  connection targets (previously implicit via `auth login --name`).
+  Removing the *current* context requires explicit `-y` (exit-10 protocol)
+  because subsequent commands have no default target.
+- `auth refresh` — exchanges the stored refresh token for a new access +
+  refresh pair (OAuth refresh-token grant). Transparent 401 → refresh →
+  retry is also wired into the SDK transport with singleflight de-dup, so
+  most callers never need to invoke this explicitly.
+- `kb edit` — partial-update edit with only-sent-fields semantics
+  (`*string` options so unset fields stay unset in the PUT body).
+- `kb pin` / `kb unpin` — idempotent pin/unpin toggle; no-op when already
+  in the target state (emits `_meta.warnings`, no server call).
+- `kb empty` — bulk-delete documents while preserving the KB record and
+  its config. High-risk-write; exit-10 confirmation in non-TTY / `--json`
+  paths; `--dry-run` emits `risk` + `dry_run:true`.
+- `doc download` — stream a knowledge file to disk (`-O FILE` /
+  `-O -` for stdout) with `--clobber` controlling overwrite. Rejects
+  server-supplied path-like filenames; partial writes on error are
+  cleaned up.
+- `doc upload --recursive --glob '*.md'` — walk a directory and upload
+  every match. Per-file `OK` / `FAIL` progress lines on the human path;
+  aggregated `uploaded[]` / `failed[]` envelope on `--json`. Exit code
+  typed to the first failure's class on partial failure.
+- `search chunks` / `search kb` / `search docs` / `search sessions` —
+  verb-noun subtree (gh `search code/repos/issues/…` shape). `search
+  chunks` is hybrid (vector + keyword) retrieval; the other three are
+  client-side substring filters useful for discovering identifiers.
+  All four take `--limit N` / `-L N` (1..1000) to cap returned rows.
+- `session list` / `session view` / `session delete` — chat session
+  management.
+- `api --input FILE` / `api --input -` — body source for raw HTTP
+  passthrough (file or stdin); mutually exclusive with `--data`.
+- Completion smoke test guards against cobra bumps silently breaking
+  bash / zsh / fish / powershell completion.
+
+#### SDK additions (Go client at `client/`, strictly additive)
+- `OpenKnowledgeFile(ctx, id) (filename, body io.ReadCloser, err)` — new
+  primitive returning the body as a stream plus the server-suggested
+  Content-Disposition filename. `DownloadKnowledgeFile` is now a thin
+  wrapper (signature unchanged, gained partial-file-on-error cleanup).
+- `WithTransport(http.RoundTripper) ClientOption` — lets the CLI install
+  the 401-retry transport.
+- `PathAuthLogin` / `PathAuthRefresh` constants — so HTTP middleware
+  doesn't re-hardcode the literals.
+- `IsPinned bool` field on `KnowledgeBase` (server already returned it;
+  SDK just hadn't modeled it).

cli/README.md

@@ -18,7 +18,8 @@ Available Commands:
   doctor      Run 4 self-checks: base URL, auth, server version, credential storage
   kb          Manage knowledge bases
   link        Bind the current directory to a knowledge base
-  search      Hybrid (vector + keyword) chunk retrieval against a knowledge base
+  search      Search across chunks, knowledge bases, documents, or sessions
+  session     Manage chat sessions
   version     Show CLI build metadata
 ```
 
@@ -69,7 +70,7 @@ weknora link --kb my-knowledge-base
 weknora doc upload notes.md
 
 # 6. Search
-weknora search "what is reciprocal rank fusion?"
+weknora search chunks "what is reciprocal rank fusion?"
 
 # 7. Ask the LLM (streams to terminal)
 weknora chat "summarise the design doc"

cli/acceptance/contract/envelope_test.go

@@ -17,7 +17,7 @@
 //                                               (--with-token) + keyring-aware
 //                                               Secrets store; helpers_test
 //                                               (PR-6) does not yet expose a
-//                                               stdin hook. Deferred to v0.2 e2e.
+//                                               stdin hook. Deferred to the e2e harness.
 //   - auth_login.error_auth_unauthenticated   — same setup as above; deferred
 //                                               together.
 //   - context_use.error_local_context_not_found — `context use` has no --json

cli/acceptance/doc.go

@@ -6,9 +6,7 @@
 //
 // Sub-packages:
 //   contract/    — envelope JSON shape golden + error.code registry consistency
-//
-// Future v0.2+:
 //   e2e/         — real WeKnora server blackbox tests (testscript-style)
 //
-// Mirrors gh's acceptance/ + kubernetes test/e2e/ pattern (spec §4.5).
+// Layout convention follows spec §4.5.
 package acceptance

cli/cmd/root.go

@@ -139,7 +139,7 @@ hybrid searches against a WeKnora server from your shell or an AI agent.`,
 		Example: `  weknora auth login --host=https://kb.example.com   # one-time setup
   weknora kb list                                    # list knowledge bases
   weknora kb view <id>                               # show one
-  weknora search "your question" --kb=<id>           # hybrid retrieval
+  weknora search chunks "your question" --kb=<id>    # hybrid retrieval
   weknora doctor --json                              # health check (agent-readable)`,
 		SilenceUsage:  true,
 		SilenceErrors: true,