Cross-cutting cleanup that lands alongside the new feature surface:
- `--limit / -L` and `--all-pages` on every list command. Default
--limit 30 (gh-parity); --all-pages drains every server page
client-side, capped by --limit. Closes the audit finding that the
old "1000 max per call" implicit cap was undiscoverable.
- `auth token` emits a TTY-only stderr advisory when stdout is a
terminal (the credential just got displayed in scrollback) plus an
api-key-mode rotation hint.
- Comment + doc discipline pass: drop external project name
references from in-code comments (we reference them in design notes,
not inline).
- Bump `go` directive to 1.26.0 and CI matrix to 1.26.x to align with
the main module's go.mod.
- Rename `cli/internal/agent` → `cli/internal/aiclient` to
disambiguate from the new `cli/cmd/agent` resource subtree. The
package handles AI coding-agent env detection + per-command --help
annotations; the new name reflects that more precisely.
`weknora mcp serve` — long-lived stdio MCP (Model Context Protocol)
transport that exposes a fixed, curated tool surface to MCP-aware
agents (Claude Desktop, Claude Code, custom MCP clients).
Curated tool set (readonly by default):
- whoami — active context + tenant
- search (hybrid retrieval against a KB)
- kb list / view
- doc list / view
- agent list / view / invoke
- session list / view
The list is intentionally narrow to the read + agent-invoke surface;
destructive verbs (`delete` / `empty` / `upload`) are gated behind
`--write`. Schema is built from each leaf cobra command's flags so
adding a new tool is a single registry entry plus a Service interface.
Includes the simplify post-review polish + a second simplify pass to
fold the resulting feedback (typed schemas, agent_help wording, unify
chat / agent invoke option names).
Output ergonomics:
- `--json` accepts a comma-separated field list (gh-parity); selects
named keys from the per-command payload. Bare `--json` keeps the
full shape.
- `--jq <expr>` evaluates a gojq expression over the JSON; pairs with
`--json field-list` so projection runs before jq.
- `--version` is a global cobra flag in addition to the `version`
subcommand; both render the same line.
- Per-command `--help` now renders the available JSON field list under
"JSON fields available via `--json id,name,...`" (field-discovery
parity with gh / kubectl `-o jsonpath`).
New commands:
- `auth token` — print the active context's credential to stdout for
shell command substitution (`WEKNORA_TOKEN=$(weknora auth token)`).
Default: raw secret, no trailing newline. `--json` emits
`{token, mode, context}`.
- `doc upload --from-url <URL>` — ingest a remote URL via the SDK
`CreateKnowledgeFromURL`. `--name` forwarded as `FileName` so the
server's known-extension heuristic upgrades crawl-mode to
file-download-mode where appropriate.
Includes the simplify post-review polish pass (field-filter unit
tests, --json/--jq compose check, agent_help copy fixes).
Borrows the lark-cli agent-affordance model
(https://github.com/larksuite/cli/blob/main/AGENTS.md +
skills/lark-shared/SKILL.md) so weknora is designed to be agent-friendly:
error messages, output format, and flag design follow conventions agents
can rely on.
cli/AGENTS.md (operational reference for LLM agents invoking weknora):
Public document covering envelope schema, exit-code protocol
(0/1/2/10/130), stdout/stderr separation, and behavioral rules.
Sensitive commands (\`context use\`, \`kb delete\`, \`doc delete\`, \`init\`)
gain "AI agents:" paragraphs in their cobra Long descriptions so
guidance shows in --help.
format.Envelope schema additions:
Risk per-operation classification (read / write / high-risk-write +
action description), populated by write commands on both success
and failure paths.
Notice system advisories (CLI update available, server-CLI version
skew); type defined, emit sites land in v0.3.
DryRun marker for envelopes returned from --dry-run preview paths.
RiskLevel constants realigned to lark's taxonomy: read / write /
high-risk-write (was: read / mutating / destructive — not yet wired by
any command).
cmdutil.Error gains OperationRisk; PrintErrorEnvelope auto-attaches it
to envelope.Risk so destructive failure paths surface uniformly.
Exit-10 confirmation protocol:
New ErrorCode \`input.confirmation_required\` mapped to exit code 10 in
cmdutil.ExitCode. ConfirmDestructive now returns this code (with
OperationRisk attached) when stdout is non-TTY or --json was set, with
-y/--yes absent. Previous behavior — silent proceed in non-TTY — was
unsafe: scripts and agents could delete resources with no explicit
approval. Three test cases re-pinned around the new contract.
This is a wire-contract change for any caller who relied on silent
proceed; v0.0/v0.1 had no destructive commands, so the blast radius is
contained to v0.2 itself.
--dry-run global flag:
cmd write paths (kb create/delete, doc upload/delete, api POST/PUT/PATCH/
DELETE) check cmdutil.IsDryRun(cmd) and skip the SDK call, emitting an
envelope with dry_run=true plus a Risk classification. Read commands
ignore --dry-run by design (no side effect to preview). Human-mode
prints \`[dry-run] would <action>\` to stdout.
Command discovery: agents introspect via the existing \`--help\` surface
(consistent with gh / kubectl / aws / gcloud / terraform — none of them
ship a CLI-tree self-description command). An earlier draft added a
\`weknora schema\` reflection command; dropped after a mainstream survey
found it has no stable analog (lark-cli's schema describes Lark API
methods, not its own CLI tree).
Tests: 27 cli packages pass at this commit. Added two new tests covering
envelope.risk and envelope._notice serialization.
text/ gh-style display-width string helpers (Truncate / FuzzyAgo / Pluralize)
compat/ server-CLI version skew probe (kubectl) + 24h TTL cache (gh internal/update)
acceptance/contract/ helpers_test.go for in-process cobra exec + golden assert
(uses iostreams.SetForTest singleton replacement; no t.Parallel)
cmdutil/errors.go: AllCodes() + ClassifyHTTPErrorOutputs() bridge for the
contract test suite (no behavior change in error handling)
go-runewidth promoted from indirect to direct (used by text.Truncate for
display-width-aware CJK truncation).
acceptance/contract/helpers_test.go forward-references cmd.NewRootCmd which
is exported in PR-7 — that file does not compile until then by design.
nullkey