Polish MCP ingest and schema surfaces

1 files changed, 98 insertions, 1 deletions

diff --git a/README.md b/README.md
index 4540fcd..9e30b28 100644
--- a/README.md
+++ b/README.md
@@ -63,6 +63,47 @@ cargo run -p fidget-spinner-cli -- frontier init \
   --primary-metric-objective maximize
 ```
 
+Register project-level metric and run-dimension vocabulary before recording a
+lot of experiments:
+
+```bash
+cargo run -p fidget-spinner-cli -- schema upsert-field \
+  --project . \
+  --name scenario \
+  --class change \
+  --class analysis \
+  --presence recommended \
+  --severity warning \
+  --role projection-gate \
+  --inference manual-only \
+  --type string
+```
+
+```bash
+cargo run -p fidget-spinner-cli -- metric define \
+  --project . \
+  --key wall_clock_s \
+  --unit seconds \
+  --objective minimize \
+  --description "elapsed wall time"
+```
+
+```bash
+cargo run -p fidget-spinner-cli -- dimension define \
+  --project . \
+  --key scenario \
+  --type string \
+  --description "workload family"
+```
+
+```bash
+cargo run -p fidget-spinner-cli -- dimension define \
+  --project . \
+  --key duration_s \
+  --type numeric \
+  --description "time budget in seconds"
+```
+
 Record low-ceremony off-path work:
 
 ```bash
@@ -76,17 +117,33 @@ cargo run -p fidget-spinner-cli -- tag add \
 cargo run -p fidget-spinner-cli -- research add \
   --project . \
   --title "next feature slate" \
-  --body "Investigate pruning, richer projections, and libgrid schema presets."
+  --summary "Investigate the next tranche of high-value product work." \
+  --body "Investigate pruning, richer projections, and libgrid schema presets." \
+  --tag dogfood/mvp
 ```
 
 ```bash
 cargo run -p fidget-spinner-cli -- note quick \
   --project . \
   --title "first tagged note" \
+  --summary "Tag-aware note capture is live." \
   --body "Tag-aware note capture is live." \
   --tag dogfood/mvp
 ```
 
+```bash
+cargo run -p fidget-spinner-cli -- metric keys --project .
+```
+
+```bash
+cargo run -p fidget-spinner-cli -- metric best \
+  --project . \
+  --key wall_clock_s \
+  --dimension scenario=belt_4x5 \
+  --dimension duration_s=60 \
+  --source run-metric
+```
+
 Serve the local MCP surface in unbound mode:
 
 ```bash
@@ -145,6 +202,8 @@ The current MCP tools are:
 - `project.bind`
 - `project.status`
 - `project.schema`
+- `schema.field.upsert`
+- `schema.field.remove`
 - `tag.add`
 - `tag.list`
 - `frontier.list`
@@ -158,10 +217,22 @@ The current MCP tools are:
 - `node.archive`
 - `note.quick`
 - `research.record`
+- `metric.define`
+- `metric.keys`
+- `metric.best`
+- `metric.migrate`
+- `run.dimension.define`
+- `run.dimension.list`
 - `experiment.close`
 - `skill.list`
 - `skill.show`
 
+Nontrivial MCP tools follow the shared presentation contract:
+
+- `render=porcelain|json` chooses terse text vs structured JSON rendering
+- `detail=concise|full` chooses triage payload vs widened detail
+- porcelain is default and is intentionally not just pretty-printed JSON
+
 Operationally, the MCP now runs as a stable host process that owns the public
 JSON-RPC session and delegates tool execution to an internal worker subprocess.
 Safe replay is only allowed for explicitly read-only operations and resources.
@@ -172,6 +243,31 @@ created with `tag.add`, each with a required human description. `note.quick`
 accepts `tags: []` when no existing tag applies, but the field itself is still
 mandatory so note classification is always conscious.
 
+`research.record` now also accepts optional `tags`, so rich imported documents
+can join the same campaign/subsystem index as terse notes without falling back
+to the generic escape hatch.
+
+`note.quick`, `research.record`, and generic `node create` for `note`/`research`
+now enforce the same strict prose split: `title` is terse identity, `summary`
+is the triage/search layer, and `body` holds the full text. List-like surfaces
+stay on `title` + `summary`; full prose is for explicit reads only.
+
+Schema authoring no longer has to happen by hand in `.fidget_spinner/schema.json`.
+The CLI exposes `schema upsert-field` / `schema remove-field`, and the MCP
+surface exposes the corresponding `schema.field.upsert` / `schema.field.remove`
+tools. The CLI uses space-separated subcommands; the MCP uses dotted tool names.
+
+Metrics and run dimensions are now project-level registries. Frontier contracts
+still declare the evaluation metric vocabulary, but closed experiments report
+only thin `key=value` metrics plus typed run dimensions. `metric.define` can
+enrich metric descriptions, CLI `dimension define` / MCP `run.dimension.define`
+preregister slicers such as `scenario` or `duration_s`, `metric.keys`
+discovers rankable numeric signals, and `metric.best` ranks one key within
+optional exact dimension filters.
+Legacy `benchmark_suite` data is normalized into a builtin string dimension on
+store open, and `metric.migrate` can be invoked explicitly as an idempotent
+repair pass.
+
 The intended flow is:
 
 1. inspect `system.health`
@@ -190,6 +286,7 @@ Off-path work does not require git. You can initialize a local project and use:
 - `research add`
 - `tag add`
 - `note quick`
+- `metric keys`
 - `node annotate`
 - `mcp serve`