feat(cli)!: v0.10 reliability, agent-UX, and command-surface hardening

A hardening + finalization pass over the agent-first CLI: correctness fixes,
richer machine-readable signals, flag/naming consistency, and a symmetric
config surface. Pre-1.0, so it includes breaking renames.

Correctness:
- agent update: resolve/validate --model/--rerank-model (was storing a bogus
  name verbatim, corrupting config.model_id).
- doctor: honor WEKNORA_HOST / WEKNORA_API_KEY (headless path no longer reports
  "no host configured").
- session ask / MCP session_ask: text answer was empty on non-TTY — the agent
  stream sets Done=true on an intermediate agent_query frame before the answer,
  and AgentAccumulator treated the first Done as terminal. Terminate on the
  `complete` event (new sdk.AgentResponseTypeComplete), not a per-frame Done.
- batch exit codes: any per-item failure collapses to operation.failed (exit 1),
  including `doc upload --recursive` partial failures — a permanent per-file
  failure (e.g. a duplicate) no longer surfaces as a retryable exit 7 an agent
  would loop on; per-item typed errors stay in the envelope.

Agent-first signals & discovery:
- error.exit_code in the envelope (type + exit_code disambiguate the
  input.invalid_argument exit-2-vs-5 split in one JSON read).
- meta.hint on empty content search and on draft doc create; doc wait fails fast
  on a never-parsing draft instead of hanging to --timeout.
- retrieval-readiness is visible in the natural flow: kb status / kb check emit
  retrieval_ready, and kb create hints the fix when no embedding model is bound
  — an unconfigured KB no longer looks silently healthy.
- schema contract completeness: every leaf declares output + >=1 example
  (drift-guarded); output strings match the meta actually emitted; chunk list
  and search docs now emit meta.total_count (both previously dropped it).
- schema tolerates a quoted multi-word command label; zero-state auth — and
  `link` with no profile — point at profile setup / the headless WEKNORA_KB_ID
  path instead of looping on `auth login`.
- id-addressed reads tolerate a redundant --kb (doc view/wait, chunk list/view
  accept and ignore it, declared in schema) so a carried-over --kb doesn't
  exit 2; streaming commands warn that --jq does not apply to an NDJSON stream.
- keep JSON-always as the default; --jq hints spell out the .data path.

Consistency & gating:
- doc create: drop the deprecated --name alias (--title only; pre-1.0 break).
- chunk list --limit aligned to 1..10000; model list --limit/-L with
  has_more/total_count; api write-gates -X PUT/PATCH (exit 10); skills install
  expands a leading ~.
- docs corrected: search docs / doc list --keyword help is case-insensitive
  (server does LOWER LIKE); AGENTS.md risk-action list (no phantom kb.init; add
  model.update / kb.config.set) and batch example (failed item carries `error`);
  session resume --message id comes from `message list`, not the stream.
- auth/profile ergonomics: env credentials are now first-class — `auth token`
  prints the active WEKNORA_API_KEY / WEKNORA_TOKEN, and auth login/logout/refresh
  give an env-aware message instead of looping on "run auth login". `auth logout`
  clears credentials but keeps the profile registered (host preserved for
  re-login); deleting a profile is `profile remove`'s job (clean logout/remove
  separation, matching gh / lark).

Config surface (symmetric read/write, in-place model edits):
- kb config now returns a secret-free KBModelConfigView (was {}); `kb config`
  reads, new `kb config set` writes; `kb init` removed (misnomer).
- kb create --chat-model: retrieval-ready in one step.
- model update: edit a model in place (id preserved, references survive) —
  rotate --api-key-stdin, change base-url / display-name / etc.
- session continue-stream renamed to session resume.

Docs: AGENTS.md is the single wire-contract source; CHANGELOG slimmed; stale
kb-init / continue-stream references removed; skill wire-vocab guard extended.
AGENTS.md / weknora-shared SKILL document retrieval_ready (a KB needs an
embedding model to be searchable), that --jq does not apply to NDJSON
streams, and the env-credential-first auth path; the KB quickstart example
now creates a retrieval-ready KB.

cli/cmd/doc/create.go

@@ -12,6 +12,7 @@ import (
 
 	"github.com/Tencent/WeKnora/cli/internal/cmdutil"
 	"github.com/Tencent/WeKnora/cli/internal/iostreams"
+	"github.com/Tencent/WeKnora/cli/internal/output"
 	sdk "github.com/Tencent/WeKnora/client"
 )
 
@@ -26,17 +27,12 @@ var docCreateFields = []string{
 // CreateOptions holds CLI flag values for `doc create`.
 type CreateOptions struct {
 	Text    string // --text (required): document text content (Markdown)
-	Title   string // --title: document title (preferred; matches `doc update --title`)
-	Name    string // --name: deprecated alias for --title
+	Title   string // --title: document title (matches `doc update --title`)
 	TagID   string // --tag-id: associate with a tag
 	Channel string // --channel: ingestion-channel tag (default "api")
 	DryRun  bool
 }
 
-// title returns the resolved document title, preferring --title over the
-// deprecated --name alias.
-func (o *CreateOptions) title() string { return cmp.Or(o.Title, o.Name) }
-
 // CreateService is the narrow SDK surface for `doc create`.
 // *sdk.Client satisfies it.
 type CreateService interface {
@@ -84,7 +80,7 @@ don't require a file upload or remote URL. KB resolution follows the standard
 					Action: "doc.create",
 					Args: map[string]any{
 						"text":  opts.Text,
-						"title": opts.title(),
+						"title": opts.Title,
 						"kb":    kbID,
 					},
 				}); handled {
@@ -106,8 +102,6 @@ don't require a file upload or remote URL. KB resolution follows the standard
 	cmdutil.AddKBFlag(cmd)
 	cmd.Flags().StringVar(&opts.Text, "text", "", "Document text content in Markdown format (required)")
 	cmd.Flags().StringVar(&opts.Title, "title", "", "Document title")
-	cmd.Flags().StringVar(&opts.Name, "name", "", "Document title (deprecated: use --title)")
-	_ = cmd.Flags().MarkDeprecated("name", "use --title instead")
 	cmd.Flags().StringVar(&opts.TagID, "tag-id", "", "Tag id to associate with the new entry")
 	cmd.Flags().StringVar(&opts.Channel, "channel", "", "Ingestion-channel tag recorded server-side (default \"api\")")
 	_ = cmd.MarkFlagRequired("text")
@@ -134,7 +128,7 @@ func runCreate(ctx context.Context, opts *CreateOptions, fopts *cmdutil.FormatOp
 		return cmdutil.NewFlagError(fmt.Errorf("--text is required"))
 	}
 	req := &sdk.CreateManualKnowledgeRequest{
-		Title:   opts.title(),
+		Title:   opts.Title,
 		Content: opts.Text,
 		TagID:   opts.TagID,
 		Channel: cmp.Or(opts.Channel, uploadChannel),
@@ -143,10 +137,18 @@ func runCreate(ctx context.Context, opts *CreateOptions, fopts *cmdutil.FormatOp
 	if err != nil {
 		return cmdutil.WrapHTTP(err, "create document")
 	}
-	if fopts.WantsJSON() {
-		return fopts.Emit(iostreams.IO.Out, k, nil)
+	// Inline-created docs land in parse_status=draft and are NOT auto-queued
+	// for parsing (unlike `doc upload`), so they aren't searchable until
+	// reparsed. Surface the next step so an agent doesn't `doc wait` into a
+	// timeout or `search` into empty results.
+	var meta *output.Meta
+	if k.ParseStatus == "draft" {
+		meta = &output.Meta{Hint: "document created in parse_status=draft (not yet indexed) — run `weknora doc reparse " + k.ID + "` to parse & make it searchable"}
 	}
-	displayed := opts.title()
+	if fopts.WantsJSON() {
+		return fopts.Emit(iostreams.IO.Out, k, meta)
+	}
+	displayed := opts.Title
 	if displayed == "" {
 		displayed = k.Title
 	}
@@ -154,5 +156,8 @@ func runCreate(ctx context.Context, opts *CreateOptions, fopts *cmdutil.FormatOp
 		displayed = k.ID
 	}
 	fmt.Fprintf(iostreams.IO.Out, "✓ Created %q (id: %s)\n", displayed, k.ID)
+	if meta != nil {
+		fmt.Fprintf(iostreams.IO.Out, "  ⚠ %s\n", meta.Hint)
+	}
 	return nil
 }

cli/cmd/doc/create_test.go

@@ -35,28 +35,21 @@ func (f *fakeCreateSvc) CreateManualKnowledge(
 	return f.resp, f.err
 }
 
-// TestCreate_TitlePreferredOverName: --title is the canonical flag; the
-// deprecated --name remains a working alias but --title wins when both are set.
-func TestCreate_TitlePreferredOverName(t *testing.T) {
+// TestCreate_TitleSetsRequestTitle: --title is the sole title flag and flows
+// straight into the create request.
+func TestCreate_TitleSetsRequestTitle(t *testing.T) {
 	_, _ = iostreams.SetForTest(t)
 	svc := &fakeCreateSvc{resp: &sdk.Knowledge{ID: "d1"}}
 	require.NoError(t, runCreate(context.Background(),
-		&CreateOptions{Text: "x", Title: "FromTitle", Name: "FromName"},
+		&CreateOptions{Text: "x", Title: "FromTitle"},
 		&cmdutil.FormatOptions{Mode: cmdutil.FormatText}, svc, "kb1"))
 	assert.Equal(t, "FromTitle", svc.got.req.Title)
-
-	// --name alone still works (back-compat for the deprecated alias).
-	svc2 := &fakeCreateSvc{resp: &sdk.Knowledge{ID: "d2"}}
-	require.NoError(t, runCreate(context.Background(),
-		&CreateOptions{Text: "x", Name: "OnlyName"},
-		&cmdutil.FormatOptions{Mode: cmdutil.FormatText}, svc2, "kb1"))
-	assert.Equal(t, "OnlyName", svc2.got.req.Title)
 }
 
 func TestCreate_Success_Text(t *testing.T) {
 	out, _ := iostreams.SetForTest(t)
 	svc := &fakeCreateSvc{resp: &sdk.Knowledge{ID: "doc_manual_1", Title: "Sprint Notes"}}
-	opts := &CreateOptions{Text: "# Sprint Notes\n\nAction items: ...", Name: "Sprint Notes"}
+	opts := &CreateOptions{Text: "# Sprint Notes\n\nAction items: ...", Title: "Sprint Notes"}
 	require.NoError(t, runCreate(context.Background(), opts, &cmdutil.FormatOptions{Mode: cmdutil.FormatText}, svc, "kb_xxx"))
 
 	assert.Equal(t, "kb_xxx", svc.got.kbID)
@@ -110,7 +103,7 @@ func TestCreate_Channel_DefaultIsAPI(t *testing.T) {
 func TestCreate_JSON_Envelope(t *testing.T) {
 	out, _ := iostreams.SetForTest(t)
 	svc := &fakeCreateSvc{resp: &sdk.Knowledge{ID: "doc_manual_json", Title: "My Note"}}
-	opts := &CreateOptions{Text: "# My Note", Name: "My Note"}
+	opts := &CreateOptions{Text: "# My Note", Title: "My Note"}
 	fopts := &cmdutil.FormatOptions{Mode: cmdutil.FormatJSON}
 	require.NoError(t, runCreate(context.Background(), opts, fopts, svc, "kb_xxx"))
 

cli/cmd/doc/download.go

@@ -79,11 +79,16 @@ stdout.`,
 	}
 	cmd.Flags().StringVarP(&opts.Output, "output", "O", "", `Output path; "-" for stdout. Defaults to the server-suggested filename.`)
 	cmd.Flags().BoolVar(&opts.Clobber, "clobber", false, "Overwrite the output file if it already exists")
+	cmdutil.AddIgnoredKBFlag(cmd)
 	cmdutil.AddFormatFlag(cmd, downloadFields...)
 	cmdutil.SetAgentHelp(cmd, cmdutil.AgentHelp{
 		UsedFor:       "Download a document's bytes by id. Writes a file (or stdout with --output -).",
 		RequiredFlags: []string{"<doc-id> (positional)"},
 		Output:        "with --format json (file output): envelope.data has path, bytes, filename; suppressed with --output - (raw bytes to stdout)",
+		Examples: []string{
+			"weknora doc download doc_abc --output ./manual.pdf",
+			"weknora doc download doc_abc --output - > manual.pdf",
+		},
 	})
 	return cmd
 }

cli/cmd/doc/list.go

@@ -106,7 +106,7 @@ backend storage order is not guaranteed and varies between deployments.`,
 	cmd.Flags().IntVarP(&opts.Limit, "limit", "L", 30, "Maximum results to return — client-side cap; meta.has_more/total_count report the full size (1..10000)")
 	cmd.Flags().BoolVar(&opts.AllPages, "all-pages", false, "Walk all server pages until exhausted (or --limit hit)")
 	cmd.Flags().StringVar(&opts.Status, "status", "", "Filter by parse status: pending | processing | completed | failed")
-	cmd.Flags().StringVar(&opts.Keyword, "keyword", "", "Server-side substring match against title / file_name (case-sensitive)")
+	cmd.Flags().StringVar(&opts.Keyword, "keyword", "", "Server-side substring match against title / file_name (case-insensitive)")
 	cmd.Flags().StringVar(&opts.FileType, "file-type", "", `Filter by file extension (e.g. "pdf", "md")`)
 	cmd.Flags().StringVar(&opts.Source, "source", "", `Filter by ingestion source (e.g. "api", "web")`)
 	cmd.Flags().StringVar(&opts.TagID, "tag-id", "", "Filter by tag association")
@@ -116,7 +116,7 @@ backend storage order is not guaranteed and varies between deployments.`,
 	cmdutil.SetAgentHelp(cmd, cmdutil.AgentHelp{
 		UsedFor:  "List documents in the resolved knowledge base. Results come with meta.count; use --limit to cap, --all-pages to walk every server page, --status/--keyword to filter server-side.",
 		Examples: []string{"weknora doc list --format json", "weknora doc list --all-pages --limit 200 --format json"},
-		Output:   "envelope.data is an array of Knowledge objects with id, title, file_name, parse_status; meta.count is the total returned; meta.total_count is the server-side total before client-side --limit truncation",
+		Output:   "envelope.data is an array of Knowledge objects with id, title, file_name, parse_status; meta.count is the returned count; meta.total_count is the server-side total before client-side --limit truncation; meta.has_more=true when --limit truncated",
 	})
 	return cmd
 }

cli/cmd/doc/reparse.go

@@ -57,6 +57,7 @@ keeps its id; parsing restarts asynchronously, so follow with
 			return runReparse(c.Context(), opts, fopts, cli, args[0])
 		},
 	}
+	cmdutil.AddIgnoredKBFlag(cmd)
 	cmdutil.AddFormatFlag(cmd, docReparseFields...)
 	cmdutil.AddDryRunFlag(cmd, &opts.DryRun)
 	cmdutil.SetAgentHelp(cmd, cmdutil.AgentHelp{

cli/cmd/doc/update.go

@@ -98,6 +98,7 @@ to the user first.`,
 	}
 	cmd.Flags().StringVar(&title, "title", "", "New title (omit to leave unchanged)")
 	cmd.Flags().StringVar(&desc, "description", "", "New description (omit to leave unchanged)")
+	cmdutil.AddIgnoredKBFlag(cmd)
 	cmdutil.AddFormatFlag(cmd, docUpdateFields...)
 	cmdutil.AddDryRunFlag(cmd, &opts.DryRun)
 	cmdutil.SetWriteRisk(cmd, "doc.update")

cli/cmd/doc/upload_recursive.go

@@ -81,16 +81,11 @@ func runUploadRecursive(ctx context.Context, opts *UploadOptions, fopts *cmdutil
 	// uploaded captures per-path server results for successful uploads.
 	// Populated by the RunBatch closure; read by the resultFn below.
 	uploaded := make(map[string]uploadedFile, len(matches))
-	var firstFailCode cmdutil.ErrorCode
 	channel := cmp.Or(opts.Channel, uploadChannel)
 
 	outcomes, runErr := cmdutil.RunBatch(ctx, matches, func(ctx context.Context, p string) error {
 		k, err := svc.CreateKnowledgeFromFile(ctx, kbID, p, meta, opts.EnableMultimodel, "", channel, nil)
 		if err != nil {
-			code := cmdutil.ClassifyHTTPError(err)
-			if firstFailCode == "" {
-				firstFailCode = code
-			}
 			// Per-file progress lines are human progress signal; suppress
 			// under --format json so they don't precede the JSON object on stdout.
 			if !fopts.WantsJSON() {
@@ -133,9 +128,15 @@ func runUploadRecursive(ctx context.Context, opts *UploadOptions, fopts *cmdutil
 		// carries per-file detail; without Silent the root error handler would
 		// print to stderr in addition. ExitCode still walks Code so the typed
 		// exit-code-by-class contract holds.
-		code := firstFailCode
-		if code == "" {
-			code = cmdutil.ClassifyContextErr(ctx.Err())
+		// Any per-file failure collapses to operation.failed (exit 1) — the
+		// per-file batch envelope carries each file's typed error, which is the
+		// authoritative signal (matches doc/session/chunk batch delete). A
+		// cancelled / timed-out batch keeps its context class (124 / 130) so a
+		// permanent partial failure (e.g. a duplicate) is never misreported as a
+		// retryable 5xx that an agent would loop on.
+		code := cmdutil.CodeOperationFailed
+		if ctxErr := ctx.Err(); ctxErr != nil {
+			code = cmdutil.ClassifyContextErr(ctxErr)
 		}
 		return &cmdutil.Error{
 			Code:    code,

cli/cmd/doc/upload_recursive_test.go

@@ -109,9 +109,12 @@ func TestUploadRecursive_PartialFailure_Exits1(t *testing.T) {
 
 	var typed *cmdutil.Error
 	require.ErrorAs(t, err, &typed)
-	// CodeServerError preserves the 500 classification of the underlying
-	// SDK error - the recursive wrapper just aggregates.
-	assert.Equal(t, cmdutil.CodeServerError, typed.Code)
+	// Any per-file failure aggregates to operation.failed (exit 1), matching the
+	// batch-delete contract — a partial failure (even a permanent one like a
+	// duplicate, which classifies as server.error per-file) must not surface as
+	// a retryable exit 7 an agent would loop on. Per-file codes live in the
+	// batch envelope.
+	assert.Equal(t, cmdutil.CodeOperationFailed, typed.Code)
 
 	got := out.String()
 	assert.Contains(t, got, "OK") // ok.pdf still succeeded
@@ -267,5 +270,5 @@ func TestUploadRecursive_JSON_BatchEnvelope(t *testing.T) {
 	var typed *cmdutil.Error
 	require.ErrorAs(t, err, &typed)
 	assert.True(t, typed.Silent, "JSON-path partial failure must be Silent")
-	assert.Equal(t, cmdutil.CodeServerError, typed.Code)
+	assert.Equal(t, cmdutil.CodeOperationFailed, typed.Code)
 }

cli/cmd/doc/view.go

@@ -52,6 +52,7 @@ func NewCmdView(f *cmdutil.Factory) *cobra.Command {
 		},
 	}
 	cmdutil.AddFormatFlag(cmd, docViewFields...)
+	cmdutil.AddIgnoredKBFlag(cmd)
 	cmdutil.SetAgentHelp(cmd, cmdutil.AgentHelp{
 		UsedFor:       "fetch one document's metadata by id",
 		RequiredFlags: []string{"<doc-id> (positional)"},

cli/cmd/doc/wait.go

@@ -94,6 +94,7 @@ For fail-fast semantics, use shell composition:
 	cmd.Flags().DurationVar(&opts.Timeout, "timeout", 10*time.Minute, "Max wait time before exiting 124")
 	cmd.Flags().DurationVar(&opts.Interval, "interval", 2*time.Second, "Initial poll interval; exponential backoff capped at 15s + jitter")
 	cmdutil.AddFormatFlag(cmd)
+	cmdutil.AddIgnoredKBFlag(cmd)
 	cmdutil.SetAgentHelp(cmd, cmdutil.AgentHelp{
 		UsedFor:       "block until one or more documents reach a terminal parse state (completed or failed), or --timeout elapses",
 		RequiredFlags: []string{"<doc-id>... (one or more positionals)"},
@@ -234,6 +235,14 @@ func waitForDocs(ctx context.Context, ids []string, svc WaitService, opts WaitOp
 				case "failed":
 					addFailed(FailedDoc{ID: id, Message: doc.ErrorMessage})
 					return
+				case "draft":
+					// draft = created but NOT queued for parsing (inline
+					// `doc create` leaves docs here; file `doc upload`
+					// auto-enqueues). It never progresses on its own, so
+					// waiting would hang to the --timeout (124). Fail fast with
+					// the exact unblock command instead of silently polling.
+					addFailed(FailedDoc{ID: id, Message: "parse_status=draft: not queued for parsing — run `weknora doc reparse " + id + "` to index it"})
+					return
 				}
 
 				// Not yet terminal — sleep with jitter, then exp-backoff.

cli/cmd/doc/wait_test.go

@@ -311,3 +311,30 @@ func TestDocWait_FailureError_IsSilent(t *testing.T) {
 		t.Errorf("exit code = %d, want 1", cmdutil.ExitCode(err))
 	}
 }
+
+// TestWaitForDocs_DraftFailsFast pins that a document stuck in parse_status
+// "draft" (inline `doc create` leaves docs here; it never auto-progresses) is
+// failed fast with a reparse hint instead of polling until the --timeout.
+// Regression: `doc create` + `doc wait` used to hang to a 124 timeout.
+func TestWaitForDocs_DraftFailsFast(t *testing.T) {
+	svc := newFakeKBSvc(map[string][]string{
+		"doc_draft": {"draft", "draft", "draft"},
+	})
+	start := time.Now()
+	res, _ := waitForDocs(context.Background(), []string{"doc_draft"}, svc, WaitOptions{
+		Timeout:  5 * time.Second,
+		Interval: 1 * time.Millisecond,
+	})
+	if len(res.Timeout) != 0 {
+		t.Errorf("draft must NOT time out; got timeout=%v", res.Timeout)
+	}
+	if len(res.Failed) != 1 || res.Failed[0].ID != "doc_draft" {
+		t.Fatalf("draft doc must be failed-fast; got failed=%v", res.Failed)
+	}
+	if !strings.Contains(res.Failed[0].Message, "reparse") {
+		t.Errorf("draft failure message must point to reparse; got %q", res.Failed[0].Message)
+	}
+	if elapsed := time.Since(start); elapsed > time.Second {
+		t.Errorf("draft must fail fast (well under timeout); took %v", elapsed)
+	}
+}