Wire-contract documentation and the CI check that keeps it honest.
* cli/README.md gains a verbatim --help block (top-level + subtrees),
an Exit codes table covering 0/1/2/3/4/5/6/7/10/124/130, a "Status
vs check" verb-pair subtable, and a "doc wait" paragraph spelling out
the four exit codes (0 / 1 / 124 / 130). The api passthrough note
trims storage provider out of the deep-config list now that
kb create --storage-provider is a polished flag.
* cli/AGENTS.md becomes the contributor guide: build/test, CRUD flag
conventions, the status/check verb pattern, long-poll wait commands,
the SetAgentHelp pattern, and a full Error code reference with 35
typed codes mapped to namespaces, exit codes, retryable / hint
guidance. Reference section is bracketed by HTML markers so a CI
parity test can keep it in sync with AllCodes().
* cli/internal/cmdutil/errors_doc_test.go enforces parity: every code
in AllCodes() must appear in AGENTS.md inside the markers, and
AGENTS.md must not reference codes that no longer exist. Fails CI
if a new typed code is added without documentation.
* CHANGELOG.md gets the v0.6 entry: BREAKING (--json / --no-stream /
WEKNORA_SDK_DEBUG / kb create --name), Added (--format / --jq /
doc wait / --log-level / kb-and-agent status & check / multi-id
delete / api --paginate / MCP schema extension / SetAgentHelp /
signal-aware ctx / kb create --storage-provider / new operation.*
namespace), Changed (multi-id partial-failure exit code, doc upload
FlagError, --log-level FlagError, multi-id stdout cleanup, README /
AGENTS.md changes), with a Migration from v0.5 section walking
every BREAKING through its v0.6 replacement.
Batch-write surface and pagination consistency:
* weknora doc delete <doc-id> [<doc-id>...] — positional multi-id, default
keep-going on failure. Single -y confirms entire batch.
* weknora session delete <session-id> [<session-id>...] — same shape.
* weknora chunk delete <chunk-id> [<chunk-id>...] --doc <doc-id> — multi-id
with shared --doc parent.
* Multi-id partial-failure rolls up as operation.failed (exit 1), not
server.error (exit 7) — failures are operation outcomes, not transient
transport issues, and the retry-with-backoff hint for server.* would
mislead callers.
* weknora api <path> --paginate — auto-walks offset pagination and merges
pages into a single {data, total} JSON response.
* Paginate truncation fix across 6 list/follower call sites.
* All doc / search / chunk / session / kb list commands migrated to
FormatOptions API.
Multi-id RunE only emits the {ok, failed} envelope when the operation
actually ran — pre-flight failures (e.g. confirmation_required) leave
stdout empty per the wire contract.
doc upload's missing-positional-or-flag check is wrapped as FlagError so
the exit code (2) matches the convention used by other commands that
require a positional argument directly.
Code-reuse polish (post-implementation review pass):
- Extract text.OneLine(maxWidth, s) helper combining preview-row
normalization (newline/CR/tab → space) with text.Truncate's
UTF-8-safe truncation. Replaces agent/view.go truncate1Line (ASCII
'...' + byte-slice CJK-unsafe) and chunk/list.go singleLine.
- Lift cmdutil.OpenInput(path) for the '-' = stdin / else os.Open
pattern shared across agent create/edit and the api command.
Replaces agent/create.go's private openInput.
- Strip inline doc-spec parentheticals from source comments — those
belong in commit messages and project docs, not in source where
they rot.
Pre-PR audit fixes:
- doc upload: reject `--metadata` paired with `--from-url` as
input.invalid_argument up-front (the URL-ingest request type has
no metadata field server-side, so the pair would otherwise silently
drop). Long help and CHANGELOG updated to call out the asymmetry.
- doc upload (file path): map sdk.ErrDuplicateFile sentinel to
resource.already_exists. The sentinel arrives with no "HTTP error <n>:"
prefix because the SDK short-circuits on file-hash before reading the
HTTP status, so the previous WrapHTTP fall-through misclassified it
as network.error with a misleading "check base URL reachability" hint.
The --from-url branch already handled ErrDuplicateURL this way; this
closes the asymmetry. Caught by e2e re-upload of an already-ingested
file; regression test added.
- README exit-10 enumeration adds `agent delete` and `chunk delete`
(these were missing alongside the v0.5 destructive verbs they were
meant to gate).
Docs sync:
- cli/README.md: command tree now includes the chunk subtree; adds
agent / chunk lines to the 5-minute quickstart; adds a "Contributing
/ Reporting issues" section pointing at the repo's SECURITY.md and
AGENTS.md; drops third-party CLI parallels from the surface
description.
- cli/AGENTS.md: "Command surface design SOP" gains the
flag-vs-escape-hatch step. "CRUD command flag canon" renamed to the
hard-required-flags pattern with the contrast (TTY-prompts-fill)
defined inline rather than via opaque shorthand.
- cli/CHANGELOG.md: search docs case-sensitivity shift promoted to its
own #### Breaking changes subsection. MCP doc_list filter count
corrected from 5 to 6. Drops the bogus go.mod yaml.v3 entry (yaml.v3
was already a dependency on main; v0.5 added zero go.mod lines).
Replaces internal-Go identifiers (fuzzyTime, NoOptDefVal) with
user-language and drops the § section-symbol jargon.
New subtree (chunk list / view / delete) exposes RAG retrieval
debugging primitives with SDK-grounded field set (23 Chunk fields).
Pagination follows v0.4 canon: --limit / --page-size (1..1000) /
--all-pages.
- chunk list --doc <id>: enumerate by ChunkIndex (separate from
search chunks which is hybrid retrieval; Long help documents the
distinction)
- chunk view <id>: scope-less render via /chunks/by-id route; full
content verbatim
- chunk delete <id> --doc <id>: scope-flag + scope-id; L-13
destructive; 404 NOT idempotent; resource.not_found /
auth.forbidden / input.confirmation_required typed exit codes
documented in Long help
MCP server gains chunk_list as 10th curated tool. Schema deliberately
exposes only doc_id + limit (no pagination workflow on MCP); response
includes truncated_at_limit flag when total > limit.
cli/AGENTS.md MCP curation rationale rewritten: curated read-only is
a deliberate product call because the server side does not yet
enforce per-token scope. When server scope ships, mutation tools can
land in the MCP surface.
Shared helper cli/internal/text/timeago_string.go (FuzzyAgoStr)
extracted from session list during the C2 quality-review pass.
nullkey