// General item-level onboarding: understand structured item data, generate schema and config plans, create datasets, and create or bind apps only when the user explicitly asks for app-level setup.
Use when a user asks an agent to evaluate or tune text search similarity for an existing Viking AI Search application and dataset.
Shared SearchCLI setup: install, authenticate, run doctor, and verify the local environment.
Search runtime and scene management: run queries, inspect scenes, debug app readiness, and diagnose recall or config issues.
Provide system alias mapping for Search CLI. Invoke this skill when user mentions "Search CLI", "search_cli", or tries to execute search_cli commands.
Binds a dataset to an application with reviewed field config inference. Invoke when using `vs app dataset bind` and searchable/filter/suggest fields must be inferred and confirmed first.
Conversational search runtime: send messages, keep sessions consistent, and verify retrieval behavior and responses.
| name | vs-item-onboarding |
| description | General item-level onboarding: understand structured item data, generate schema and config plans, create datasets, and create or bind apps only when the user explicitly asks for app-level setup. |
| category | workflow |
| applies_to | codex, agents, external-agent |
| requires_cli | >=0.1.0 |
| keywords | item search onboarding, structured data onboarding, dataset-only onboarding, schema design, field config, online config, validation, recommend bootstrap, item profile, item plan, item apply |
| commands | item profile, item plan, item apply, dataset create, dataset ingest, dataset schema check, app diagnose, search run, chat run, recommend scene create |
Use this skill when a user provides structured item data and expects the agent to understand the data, design the schema, and either provision a dataset only or continue to app-level search onboarding. Understand the business goal and the requested delivery boundary first, then use item profile / plan / apply plus lower-level dataset commands to standardize the high-risk execution steps.
vs CLI and Viking skills are installedvs auth status and vs doctor succeedJSON array, JSONL, or CSV (convert binary spreadsheets first)For dataset-only, there is exactly one valid schema-level user confirmation for the current draft: Stage A. That dialog must happen only after the full schema context has been rendered.
item profile --file <data> --type <item|video> — first-pass profilingdataset-only or dataset+app; if the user did not ask for app creation, default to dataset-onlyitem plan --file <data> --type <item|video> --goal "<goal>" — generate plan directory; add --skip-app when the requested mode is dataset-only. If execution later goes through item provision or item apply, those commands also accept --skip-app as an execution-time guard rail.dataset-only, run dataset create + dataset ingest immediately after a valid Stage A answer and stop after dataset provisioning succeeds; do not issue another schema-level confirmation. Prefer creating the dataset from the full dataset-create.json payload so Schema and DataFieldConfig.FieldDescMap are submitted together. For --type video, this full-payload path is mandatory; do not use schema.json alonedataset+app, run Stage B — bind-time field-config review (table per group + dialog, see agent-confirmation-ux.md §B); for --type video apply video-field-constraints.md firstitem apply --plan-dir <dir> --confirm-review — stage-one execution for the dataset+app branch--run-trials, recommend bootstrap, app diagnose for failures. For any failure, see references/recovery.md — do NOT blindly retry.Full step-by-step workflow, dataset-type selection rules, examples, and extended guidance live in workflow.md.
See the commands: frontmatter above for the exhaustive list; the primary entry points are item profile, item plan, dataset create, dataset ingest, and item apply --plan-dir <dir> --confirm-review. Detailed command forms, flags, dataset-only branching, and dataset-type selection rules live in workflow.md.
The high-level 8-step flow is listed above under High-level Flow. The full branch-aware workflow — including dataset-only vs. dataset+app routing, profiling, plan review, Stage A, conditional Stage B, dataset provisioning, optional app provisioning, optional --run-trials, and recommend bootstrap — with per-step cross-references to the Hard Rules below lives in workflow.md.
vs CLI surface (--help, command output, and observed runtime behavior), and explicit user-provided information.The enforceable rules are organized in two layers:
vs item apply --plan-dir <dir> --confirm-review.These rules prevent server-side failures and silent data loss. Violating any rule stops the workflow.
--type <item|video> on both profile and plan. MUST NOT infer dataset type from --goal. If data looks video-like but the user did not specify, MUST ask before continuing.dataset-only or dataset+app. If the user did not ask for app creation, bind-time config, search/chat verification, or app-level setup, MUST default to dataset-only. MUST NOT create or bind an app on the user's behalf.dataset create, dataset ingest, item apply, or any app-level bind. MUST NOT treat first-pass plan generation as schema approval.schema.json; MUST NOT summarize only key fields. For --type video, MUST also surface the status of the semantic slots content_id, content_type, video_url, parent_content_id, and sequence_index before approval.dataset-only, once a valid Stage A dialog answer is captured for the current schema draft, MUST NOT ask another schema-level confirmation unless the schema changes.dataset-only request, and MUST NOT skip Stage B when app binding will happen.item plan may emit draft dataset-side config artifacts such as field-config.json or dataset-create.json with DataFieldConfig. Treat them as execution inputs, not as user-confirmed bind config. For dataset-only, dataset creation SHOULD prefer the full dataset-create.json payload so Schema and DataFieldConfig.FieldDescMap are submitted together. For dataset-only + --type video, dataset creation MUST use a full payload that includes DataFieldConfig; using only --schema @schema.json can fail with MissingParameter.DefaultFieldStrategy. For dataset-only + --type item, fall back to --schema @schema.json only when dataset-create.json is missing or clearly unsuitable for the current plan.--type video, any Stage B proposal MUST satisfy every row of video-field-constraints.md. Fix violations in memory before rendering Stage B; MUST NOT write a violating proposal to field-config.json or review-confirmation.json.vs item apply --plan-dir <dir> --confirm-review without --dry-run and MUST NOT degrade into OnlySave=true semantics.dataset-only, stage one ends after dataset creation and ingest succeed. For dataset+app, stage one ends after dataset creation, ingest, app creation, and bind succeed. MUST NOT continue beyond the requested boundary unless the user explicitly asks.--recommend-bhv-scene-types and --confirm-recommend-entry-binding.Before provisioning anything, the agent MUST first decide whether the requested path is dataset-only or dataset+app. Use the checklist below only for the dataset+app path. If the request is dataset-only, stop after Stage A and dataset provisioning; do not run Stage B or item apply.
<plan-dir> points to the latest item plan output for the current dataset (not a stale one from earlier in the conversation).plan.json.defaults.datasetType and dataset-create.json.Type both equal the requested --type (item or video).dataset+app. If not, do not run app-level provisioning.len(schema.json.Fields)), and the user answered one valid interactive question dialog with a non-abort option. For --type video, the Stage A summary also surfaced the status of content_id, content_type, video_url, parent_content_id, and sequence_index.IndexFields / FilterFields / SuggestFields / ImageIndexFields / VideoIndexFields were rendered with Field / Type / Meaning / Reason to include / Risk or note, and the user answered an interactive dialog with a non-abort option.--type video, the final proposal satisfies every row of video-field-constraints.md. MUST re-verify after any user adjustment in Stage B.field-config.json reflects the final Stage B groups, and review-confirmation.json has status=confirmed, every requiredChecks.* true, and a fieldConfigReview block with the final groups.validation.json has no unresolved blocking issues (or --force has been explicitly acknowledged by the user for a controlled test).vs item apply --plan-dir <dir> --confirm-review, with no --dry-run and without any flag that would degrade into OnlySave=true semantics.If the user makes a follow-up edit (rename a field, drop a group member, switch --type, etc.) after this checklist passed, MUST re-run the affected checks before apply.
DefaultFieldStrategy (authoritative): references/video-field-constraints.md