feat(contexto): tighten public types + honor retrieval config

[Chen17-sq]

Linked issue

Closes #133.

Summary

Addresses both bullets the issue called out:

1. Drop `any[]` from `SearchResult.items` — backend implementers ([contexto]: Implement LocalBackend #116) previously had to read `helpers.ts` to learn the item shape.
2. Honor `maxResults` from config — `engine/base.ts` was passing the hardcoded `DEFAULT_MAX_RESULTS = 7` to the backend regardless of what callers set in `BaseConfig`. `minScore` was already wired through (line 89); `filter` was also wired but undocumented.

Plus a latent bug the type tightening surfaced (see below).

What changed

1. Public types in `src/types.ts`

Two new public types replace the `any[]` and mirror `@ekai/mindmap`'s `ConversationItem` / `ScoredItem`:

export interface MindmapItem {
  id: string;
  role: string;
  content: string;
  timestamp?: string;
  metadata?: Record<string, unknown>;
}

export interface ScoredMindmapItem {
  item: MindmapItem;
  score: number;
  estimatedTokens: number;
}

export interface SearchResult {
  items: ScoredMindmapItem[];   // was: any[]
  paths?: string[][];
}

Both are re-exported from the package entry. No runtime import added — the types describe a shape, not a binding.

2. Wire `maxResults` through

- const result = await this.backend.search(query, DEFAULT_MAX_RESULTS, filter, minScore);
+ const maxResults = this.config.maxResults ?? DEFAULT_MAX_RESULTS;
+ const result = await this.backend.search(query, maxResults, filter, minScore);

`BaseConfig` gains `maxResults?: number` alongside the (already-present) `minScore` and `filter`. All three are now also declared in:

• `packages/contexto/openclaw.plugin.json` (runtime config schema)
• `packages/contexto/src/index.ts` (inline plugin definition + the `register()` reader that threads them into the engine)

3. Latent bug fix (surfaced by type tightening)

`engine/base.ts` dedup loop:

// Before
const id = (r.item ?? r).id;  // r is ScoredMindmapItem — .id lives on r.item

// After
const id = r.item?.id;

Neither backend (local + remote) returns the raw-item shape — both wrap in `{item, score, ...}` and `MindmapItem.id` is required. The `?? r` fallback was unreachable; if it ever ran, `r.id` was `undefined` and silently disabled dedup.

4. Documentation

• `packages/contexto/README.md` Configuration table gains rows for `contextEnabled`, `maxContextChars`, `maxResults`, `minScore`, `filter` (defaults inline).
• `docs/contexto.md` gets a new "Tuning Retrieval" section pointing back to the README for the full list.

Diff scope

 docs/contexto.md                       | 12 ++++++++++++
 packages/contexto/README.md            |  5 +++++
 packages/contexto/openclaw.plugin.json | 14 ++++++++++++++
 packages/contexto/src/engine/base.ts   | 18 ++++++++++++------
 packages/contexto/src/index.ts         | 15 ++++++++++++++-
 packages/contexto/src/types.ts         | 33 ++++++++++++++++++++++++++++++++-
 6 files changed, 89 insertions(+), 8 deletions(-)

Backward compatibility

Zero behaviour change for existing users:

• Adding optional fields to `BaseConfig` is non-breaking.
• The `register()` reader uses `api.pluginConfig?.` which yields `undefined` for missing keys; `engine/base.ts` then falls back to the same defaults it was hardcoding before (`DEFAULT_MAX_RESULTS = 7`, `DEFAULT_MIN_SCORE = 0.45`).
• `SearchResult.items` was `any[]` so any external code that destructured `item.content` / `item.id` / `item.metadata` still typechecks against `ScoredMindmapItem` (those fields exist on `MindmapItem`).

Test plan

• `pnpm --filter @ekai/contexto run build` (tsc --noEmit): clean.
• The latent-bug fix in `engine/base.ts` doesn't change runtime behaviour for the dominant path (where `r.item` is always populated) — it only makes the dedup work when an `{item: ..., score: ...}` shape comes back, which is the only shape the codebase actually produces.

The issue's "Tighten openclaw peerDependency version range" (#140) and "docs: Normalize docs..." (#135) are addressed in separate PRs (#147, #148) to keep diffs small per concern.