siteos-search

SiteOS Search

Read the shared execution contract once per task before choosing tools or resolving context, including when this skill is invoked directly. Apply the service-specific workflow below after that shared contract.

Hosted reads: siteos_search_list_indices, siteos_search_get_suggestions, siteos_search_query, siteos_search_list_content, siteos_search_get_visitors, siteos_search_get_relevance, siteos_search_get_connection, siteos_search_get_crawler, siteos_search_get_diagnostics and siteos_search_get_analytics.

Use this skill from the root of a target external project, or pass an explicit target project root when the user names one.

For setup or migration, start with Choose the shortest setup path: add content, check results, then add the native website interface. Reuse observed state and previously approved decisions. Select the crawler, local source-handler, prepared import or Algolia path before implementation; only the local source-handler path requires the detailed extraction session below.

This skill owns Search setup, operation and reporting. For offline export preparation, use Algolia migration; this local-only command needs no Auth or Project preflight. For editable components on any platform, use framework integration. A hosted search.js widget is not required. Use references/website-crawler.md for public HTML crawling, sitemap discovery, ownership verification, extraction, scheduled crawls and guarded automatic publication. An approved crawler source does not require local source-handler scaffolding; website UI delivery remains separate. Use references/search-experience.md for content import previews, curated suggestions, per-article activity and filters, relevance tuning, resumable installation checks and aggregate visitor analytics with optional consent control. For initial suggestions or pinning articles, use that reference’s Suggestions before typing workflow; resolve indexed document IDs and publish the ordered list without sync, reindexing or website edits once the hosted runtime is installed. For search health, usage, diagnostics, charts or sidecar reports, go directly to references/analytics-workflow.md; do not start onboarding, sync or UI changes for a reporting request. For implementation, use the connection, source, synchronization and UI workflows below. Website pageviews, custom events and conversions belong to $siteos-analytics.

Read independent indices before any hosted Search operation. Resolve the exact index after Project/environment selection and carry its ID through CLI, MCP, credentials, content, crawler and website setup. Never drop an explicit index selector after a failure.

Resolve the target through the shared execution contract. Search resource setup and indexing/query credential management use the supported CLI commands; legacy Organization tokens and Project API keys are not supported.

Do not inspect secret-bearing environment files or process environment values with output-producing commands. Determine credential readiness through safe CLI metadata and run the intended Search commands without exposing plaintext. The common CLI selection owns Project identity; no service reference file is required. Runtime query and indexing credentials belong only in the ignored owner-only project .env installed by the CLI.

Use references/siteos-connection-onboarding.md for CLI-owned SiteOS repository connection, references/source-discovery.md for candidate discovery and the combined source/UI placement checkpoint, references/source-confirmation-and-handlers.md for confirmed config and handler work, references/scaffold-contract.md for the committed scaffold and sync runner, references/ui-runtime-delivery.md for canonical SearchBar + SearchDialog UI/runtime delivery, and references/onboarding-report-template.md for user-facing onboarding reports.

On local source-handler onboarding runs only, use scripts/session-state-cli.mjs to create and maintain .siteos/temp/search/session-<started-at>.json. The JSON session file is the canonical source for siteosConnection, steps, user decisions, blockers, findings, artifacts, per-step timing metadata, checkpoint progression, cleanup confirmation, and the saved UI placement decision. Step timing is observability metadata only; it must not drive progression, checkpoint decisions, source confirmation, or sync/runtime behavior. For crawler and prepared import/migration paths, use their CLI status and preview contracts; do not create an extraction session for them, analytics or reporting.

Session State CLI Contract

Use scripts/session-state-cli.mjs as the only supported session-state interface. Do not read or import scripts/session-state.mjs during normal skill execution. If syntax is unclear, run node .agents/skills/siteos-search/scripts/session-state-cli.mjs help; do not inspect the implementation file.

For the local source-handler path, create the onboarding session immediately after the Search Project preflight determines onboarding mode or a real blocker:

node .agents/skills/siteos-search/scripts/session-state-cli.mjs init-onboarding \
  --project-root "$PWD" \
  --linkage-status missing \
  --output json

The command prints JSON containing sessionFilePath; use that exact path for later commands. If the path is not available in the current turn, resolve it without file searching:

node .agents/skills/siteos-search/scripts/session-state-cli.mjs latest \
  --project-root "$PWD" \
  --output path

For every onboarding step, mark start and completion with the known step id:

node .agents/skills/siteos-search/scripts/session-state-cli.mjs start-step \
  --session-file "$SESSION_FILE" \
  --step siteos-connection

node .agents/skills/siteos-search/scripts/session-state-cli.mjs complete-step \
  --session-file "$SESSION_FILE" \
  --step siteos-connection

Known step ids, in order:

siteos-connection
readiness-and-mode-detection
candidate-source-discovery
source-confirmation
scaffold-creation
extraction-implementation
dry-run-preview
first-live-sync
query-verification
ui-delivery
ui-placement-confirmation
ui-integration
final-verification
cleanup-confirmation

Use these exact commands for session mutations:

# Record safe SiteOS connection state.
node .agents/skills/siteos-search/scripts/session-state-cli.mjs set-siteos-connection \
  --session-file "$SESSION_FILE" \
  --linkage-status ready \
  --api-base-url-source config \
  --project-id "<project-id>" \
  --project-name "<project-name>" \
  --project-slug "<project-slug>" \
  --environment-slug "<environment-slug>" \
  --config-path "siteos-search.config.ts"

# Record a blocker and stop.
node .agents/skills/siteos-search/scripts/session-state-cli.mjs record-blocker \
  --session-file "$SESSION_FILE" \
  --code search_project_selection_required \
  --message "Select the intended Search Project through the Search CLI workflow."

# Clear blockers after the unblock action succeeds.
node .agents/skills/siteos-search/scripts/session-state-cli.mjs clear-blockers \
  --session-file "$SESSION_FILE"

# Record source and UI placement decisions after explicit user confirmation.
node .agents/skills/siteos-search/scripts/session-state-cli.mjs set-user-decisions \
  --session-file "$SESSION_FILE" \
  --confirmed-source "<source-id>" \
  --placement dedicated-page-first

# Evaluate checkpoint progression after each technical slice.
node .agents/skills/siteos-search/scripts/session-state-cli.mjs evaluate \
  --session-file "$SESSION_FILE"

Use these artifact commands instead of hand-registering artifact files:

node .agents/skills/siteos-search/scripts/session-state-cli.mjs write-source-candidates \
  --session-file "$SESSION_FILE" \
  --candidates-json '[{"id":"faq","label":"FAQ","count":9}]'

node .agents/skills/siteos-search/scripts/session-state-cli.mjs write-ui-placement-plan \
  --session-file "$SESSION_FILE" \
  --step source-confirmation \
  --content-json '{"dedicatedPageRoute":{"recommendedPath":"/search","availability":"available"}}'

node .agents/skills/siteos-search/scripts/session-state-cli.mjs write-extraction-path \
  --session-file "$SESSION_FILE" \
  --step extraction-implementation \
  --content-json '{"sources":{}}'

node .agents/skills/siteos-search/scripts/session-state-cli.mjs write-host-baseline \
  --session-file "$SESSION_FILE" \
  --step ui-delivery \
  --content-json '{"hostFramework":"detected-host-framework"}'

node .agents/skills/siteos-search/scripts/session-state-cli.mjs write-delivery-decision \
  --session-file "$SESSION_FILE" \
  --step ui-delivery \
  --content-json '{"artifactClasses":{}}'

Before cleanup, always produce the cleanup plan first; delete only after explicit user confirmation:

node .agents/skills/siteos-search/scripts/session-state-cli.mjs cleanup-plan \
  --session-file "$SESSION_FILE"

When an onboarding step needs to discover which session artifacts already exist, list artifact metadata only:

node .agents/skills/siteos-search/scripts/session-state-cli.mjs list-artifacts \
  --session-file "$SESSION_FILE"

This command returns suffixes, descriptions, filenames, and full file paths. It does not read artifact content; read an artifact file directly from disk only when that content is needed for the current step.

Unified CLI commands are the only Search credential-management boundary. Inspect safe metadata with npx @siteoshq/cli search credential list --environment <slug> --json or npx @siteoshq/cli search indexing-credential list --environment <slug> --json. Use the matching issue --install command when no suitable active credential exists, and use rotate --install only as an intentional replacement. The internal scripts/runtime-token-tooling.mjs helper supports only validate and query; it reads the exact CLI-installed variable names, never issues or rotates credentials, and never writes project files. New single-search installations use SITEOS_SEARCH_TOKEN and SITEOS_SEARCH_ENV; selected indices resolve their saved local prefix or an explicit --env-prefix. The validate command checks only local format and environment consistency without a request (status: "locally-valid"); use query with an indexed phrase to verify server access. Never create or use browser-public environment variables for the SiteOS search token, environment slug, or Search origin; this includes NEXT_PUBLIC_SITEOS_SEARCH_TOKEN, NEXT_PUBLIC_SITEOS_SEARCH_ENV, and NEXT_PUBLIC_SITEOS_SEARCH_PUBLIC_URL in Next.js projects.

npx @siteoshq/cli search credential issue --environment <slug> --install [--name <name>] --json
npx @siteoshq/cli search credential rotate --environment <slug> --install [--name <name>] --json
npx @siteoshq/cli search indexing-credential issue --environment <slug> --install [--name <name>] --json
npx @siteoshq/cli search indexing-credential rotate --environment <slug> --install [--name <name>] --json

First Pass

Resolve the target project root.
Resolve context through the shared execution contract.
Run npx @siteoshq/cli project status --json; run npx @siteoshq/cli project connect search --json when Search setup is requested and not yet attached.
Inspect the local files needed for mode selection, verify Search readiness when the selected operation needs it, classify the workflow mode, and report findings with secrets redacted.

Linkage Check

Use the shared execution contract for interface choice, target selection and access recovery.

A usable Search workspace requires the common Project selection, an explicit Search attachment and a chosen common environment. Select it with npx @siteoshq/cli project environment use <slug> --json; operational --environment flags accept common catalog slugs. The CLI resolves the resource privately; .siteos/search/project.json is not required for this workflow. Search configuration and runtime data stay service-owned; do not bypass the shared lifecycle. Use the explicitly selected common slug for CLI operations. Runtime validate/query helpers use the installed environment slug reported by credential installation; an adopted resource can retain a different native slug.

Resolve the Search API origin in this order:

The common Project origin selected through SITEOS_AUTH_BASE_URL for management.
SITEOS_SEARCH_PUBLIC_URL installed by the CLI for runtime requests.

Never use legacy Project apiBaseUrl, Server Legacy, or another product origin as a Search fallback.

For missing Search setup, load references/siteos-connection-onboarding.md. Preserve service resources and use --replace only for an authorized replacement.

Never echo authorization codes, CLI sessions, service grants, scoped credentials, Project keys, Meilisearch keys, raw headers, or full config JSON. It is safe to report safe IDs, status, metadata, and which API base URL source was selected.

API Readiness

Use the SiteOS CLI diagnostics command. Do not read .siteos/search/project.json manually for API credentials, do not run curl, and do not write inline Node HTTP clients for readiness checks:

npx @siteoshq/cli search diagnostics \
  --environment production \
  --json

If the CLI reports an API or contract failure, classify readiness as api-blocked and stop with the CLI error code/message. Do not inspect SiteOS app source code, do not use SiteOS UI, and do not use SiteOS MCP as a substitute for API readiness.

Use the CLI JSON response to classify:

ready: diagnostics status says the selected environment is ready or all blocking checks pass.
not-ready: SiteOS is reachable, but environment search health, accepted payload, sync success, or query target checks are not ready.
api-blocked: SiteOS API cannot be reached, authorization is rejected, the response is malformed, or the endpoint fails in a way that prevents a truthful readiness verdict. A 404 for the explicitly selected environment means it is unavailable or inaccessible to the current authorization; do not infer absence, select a fallback environment, or probe other environment slugs.

Before the first live sync, record the explicitly selected environment and rerun diagnostics with --environment <slug>. The unattended scaffold runner needs an indexing credential: list then issue/install or intentionally rotate/install it through the CLI. Authenticated CLI JSON imports use the Search service grant and do not need a separate indexing credential. A successful index publication makes content queryable; do not activate or manage a separate runtime.

Manage shared environments through Project settings or the common CLI:

npx @siteoshq/cli project environment list --json
npx @siteoshq/cli project environment use <slug> --json
npx @siteoshq/cli project environment create --slug <slug> --name <name> --url <url> --json
npx @siteoshq/cli project environment update <slug> --name <name> --url <url> --json

Use the explicitly selected common slug for service commands. Installed runtime values retain the actual service environment slug resolved by the CLI. Common environments start empty and never copy credentials or Production content. Service-local environment management commands are unavailable; use the shared lifecycle.

Project Shape Inspection

Inspect only enough local files to choose the next workflow and prepare later phases:

package.json: package manager hints, framework dependencies, and scripts relevant to later verification.
TypeScript presence: tsconfig.json, .ts, .tsx, and package dependencies.
Host framework evidence: framework dependencies, config files, route conventions, and project-owned build scripts. Record the discovered framework or unknown; do not reject a project because it is not Next.js.
Next.js App Router presence: src/app or app, only when Next.js is detected.
Next.js Pages Router presence: src/pages or pages, only when Next.js is detected.
Existing search surfaces: obvious search trigger/dialog components, src/lib/**search**, project-owned suggestion datasets, and any existing SiteOS search runtime files.
SiteOS search config: root siteos-search.config.ts.

Do not execute arbitrary project code during this foundation step. Read files and inspect paths only.

Mode Selection

This config-file classification applies to the local source-handler path. For crawler and prepared import/migration paths, inspect their remote status and content instead; absence of a local siteos-search.config.ts does not mean an existing crawler or imported index needs setup again.

Choose exactly one mode:

onboarding: canonical Auth and the stable Project binding are usable, SiteOS API readiness is not api-blocked, and root siteos-search.config.ts does not exist.
existing-search: the common Project has an explicit Search attachment, root siteos-search.config.ts exists and is readable, and SiteOS API readiness is not api-blocked.
repair-blocked: canonical Auth or stable Project binding is unavailable, the API cannot produce a truthful readiness verdict after connection, or an existing siteos-search.config.ts is unreadable.

not-ready diagnostics do not automatically block onboarding or existing-search mode. Report the failing readiness codes and make readiness repair the first checkpoint inside the selected mode unless the API failure itself prevents safe continuation. Before the first live sync, the expected no-successful-sync readiness state is not a reason to activate or create a separate runtime.

Required Report Shape

For first-pass mode selection, report in a concise, deterministic shape:

SiteOS search mode: onboarding | existing-search | repair-blocked
Project root: <path>
SiteOS linkage: present | missing | malformed
API base URL source: env | config | default
API readiness: ready | not-ready | api-blocked
Search config: present | missing | unreadable
Host framework: <detected framework or unknown>
Router conventions: <short discovered summary or unknown>
Existing search surfaces: <short list or none found>
Next checkpoint: <one concrete checkpoint>

Include relevant machine-readable diagnostic codes when the API returns them, but keep prose short. Redact all secrets.

After successful search delivery, state the safe Search Project name/slug and environment slug. Make clear that opening SiteOS UI is not required. Present a safe destination only when an existing command returns one. If the user asks for a signed-in browser and no safe destination is available, explain that /search runs inside the shared SiteOS shell with the canonical host-only Auth session. Do not invent or run a handoff command, and never extract, print, or reconstruct a handoff URL.

For onboarding decision checkpoints and blockers after mode selection, use references/onboarding-report-template.md. The report title must be exactly SiteOS Search Onboarding Flow. Do not include a generic status table, completed-step recap, or remaining-step plan.

Workflow Routing

For onboarding with local source handlers, initialize or update the session only through scripts/session-state-cli.mjs, then route each step through the linked references. Continue automatically through technical steps until session-state-cli.mjs evaluate reports a user-decision checkpoint or a real blocker. The only routine user-decision checkpoint is the combined source/result-reference and search UI placement confirmation before scaffold/source-handler work starts. For crawler or prepared import/migration onboarding, follow setup paths and the selected path's status/preview operations without entering scaffold steps.

For existing-search, treat siteos-search.config.ts, scripts/siteos-search/**, and the search:sync package script as reviewable search implementation state. Route source changes through references/source-discovery.md and references/source-confirmation-and-handlers.md, runtime-token repair through scripts/runtime-token-tooling.mjs, sync/scaffold repair through references/scaffold-contract.md, and UI/runtime repair through references/ui-runtime-delivery.md.

For repair-blocked, stop with one repair action:

delegate Auth or Organization repair to $siteos-auth
repair Search Project selection with the Search-owned CLI workflow
set or remove SITEOS_SEARCH_PUBLIC_URL
restore or make siteos-search.config.ts readable
retry diagnostics after SiteOS API reachability is restored

Hard Stops

Stop before:

confirming sources on behalf of the user
authoring source entries in siteos-search.config.ts without explicit user confirmation
adding source handlers without explicit user confirmation
extracting unconfirmed sources, ambiguous sources, or data that requires unresolved credentials, permissions, or result-reference decisions
executing live pnpm search:sync against SiteOS before source extraction, an explicit environment selection, and diagnostics readiness are complete
pushing or syncing data to SiteOS
exposing project API keys, bearer tokens, or raw linkage data to browser/client files
overwriting existing UI/runtime files without explicit approval
running browser UI verification before the UI/runtime delivery and wiring checkpoint
starting onboarding or changing Search configuration for a reporting-only request instead of using references/analytics-workflow.md
installing SiteOS MCP
changing SiteOS API, DB schema, CLI behavior, or exported-project behavior
installing global browser automation packages for verification

Public delivery and large imports

Use siteos search delivery status --environment SLUG --json before selecting direct Edge delivery. Configure only an explicitly public index with exact website origins, a reviewed JSON settings file and siteos search delivery configure --environment SLUG --file delivery.json --apply --json. See framework integration. Never expose a private query key. Large content snapshots use the same siteos search sync preview/apply workflow up to 100 MB; transport chunks are assembled before one index replacement. See Algolia migration.